diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 1516cc42..829a9f0f 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -45,6 +45,15 @@ jobs: - name: Run Build run: dotnet docfx ci.docfx.json + - name: Generate PDF + run: dotnet docfx pdf ci.docfx.json + + - name: Copy PDF to downloads and clean up + run: | + mkdir -p _site/downloads + cp _site/pdf/MonoGameGuide.pdf _site/downloads/ + rm -rf _site/pdf + - name: Setup Pages uses: actions/configure-pages@v5 diff --git a/api/index.md b/api/index.md index 02e8a4c1..022bb3f3 100644 --- a/api/index.md +++ b/api/index.md @@ -1,10 +1,32 @@ --- -title: Reference +title: API Reference description: MonoGame API reference documentation. --- -Welcome to the **MonoGame** reference documentation! +Welcome to the **MonoGame** API reference documentation! -This area provides detailed information on each class and method in the API. +This section provides detailed information on all classes, methods, properties, and events available in the MonoGame framework. -Please view the [documentation](../articles/index.md) for how to get started and step-by-step guidance. \ No newline at end of file +## Namespaces Overview + +The MonoGame API is organized into the following primary namespaces: + +| Namespace | Description | +| --------- | ----------- | +| **Microsoft.Xna.Framework** | Core framework classes including `Game`, `GameTime`, `Vector2`, `Matrix`, and fundamental types | +| **Microsoft.Xna.Framework.Audio** | Audio playback, sound effects, and music management | +| **Microsoft.Xna.Framework.Content** | Content loading and management with the `ContentManager` | +| **Microsoft.Xna.Framework.Graphics** | Rendering, textures, shaders, and all graphics-related functionality | +| **Microsoft.Xna.Framework.Input** | Keyboard, mouse, gamepad, and touch input handling | +| **Microsoft.Xna.Framework.Media** | Media playback for songs and videos | + +## Getting Started + +If you're new to MonoGame, we recommend starting with the [documentation](../articles/index.md) for step-by-step tutorials and guidance before diving into the API reference. + +## Common Entry Points + +- **[Game](xref:Microsoft.Xna.Framework.Game)** - The main game class you inherit from +- **[SpriteBatch](xref:Microsoft.Xna.Framework.Graphics.SpriteBatch)** - 2D rendering and sprite drawing +- **[ContentManager](xref:Microsoft.Xna.Framework.Content.ContentManager)** - Loading game assets +- **[GraphicsDeviceManager](xref:Microsoft.Xna.Framework.GraphicsDeviceManager)** - Graphics configuration diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_Architecture.md b/articles/getting_to_know/whatis/content_pipeline/CP_Architecture.md index f82c0642..482207d5 100644 --- a/articles/getting_to_know/whatis/content_pipeline/CP_Architecture.md +++ b/articles/getting_to_know/whatis/content_pipeline/CP_Architecture.md @@ -40,7 +40,7 @@ The managed code objects created by the Content Processor are serialized into a The format of data in the .XNB file is tightly coupled to the MonoGame Framework. It is not designed for use by other runtime libraries. -If you are intested in the format of the .XNB files you can view the [XNB specification](XNB Format.docx). +If you are intested in the format of the .XNB files you can view the [XNB specification](XNB%20Format.docx). ### Runtime Components diff --git a/articles/index.md b/articles/index.md index 3b2ca64f..36f9313d 100644 --- a/articles/index.md +++ b/articles/index.md @@ -20,6 +20,9 @@ This documentation [helps you to get started](getting_started/index.md) by provi Please use the links at the top and left to navigate the documentation sections. +> [!TIP] +> Looking for an offline version? [Download the PDF documentation](/downloads/MonoGameGuide.pdf). +> > This documentation assumes that the reader has a basic knowledge of the C# programming language. ## What is MonoGame exactly? diff --git a/build.ps1 b/build.ps1 index 3443d72b..b3ee9750 100644 --- a/build.ps1 +++ b/build.ps1 @@ -21,4 +21,14 @@ if (-not (Test-Path $FrameworkDll) -or -not (Test-Path $PipelineDll)) { Write-Host "Building DocFx..." -ForegroundColor Green dotnet docfx docfx.json +# Generate PDF +Write-Host "Generating PDF..." -ForegroundColor Green +dotnet docfx pdf docfx.json + +# Copy PDF to downloads folder and clean up +Write-Host "Copying PDF to downloads folder..." -ForegroundColor Green +New-Item -ItemType Directory -Force -Path "_site/downloads" | Out-Null +Copy-Item "_site/pdf/MonoGameGuide.pdf" "_site/downloads/" +Remove-Item -Path "_site/pdf" -Recurse -Force + Write-Host "Build and documentation generation completed successfully!" -ForegroundColor Green \ No newline at end of file diff --git a/build.sh b/build.sh index 210206b2..6f2876dc 100644 --- a/build.sh +++ b/build.sh @@ -21,4 +21,14 @@ fi echo "Building DocFx..." dotnet docfx docfx.json +# Generate PDF +echo "Generating PDF..." +dotnet docfx pdf docfx.json + +# Copy PDF to downloads folder and clean up +echo "Copying PDF to downloads folder..." +mkdir -p _site/downloads +cp _site/pdf/MonoGameGuide.pdf _site/downloads/ +rm -rf _site/pdf + echo "Build and documentation generation completed successfully!" \ No newline at end of file diff --git a/ci.docfx.json b/ci.docfx.json index 06e09547..d2b70072 100644 --- a/ci.docfx.json +++ b/ci.docfx.json @@ -41,6 +41,8 @@ "roadmap/**/*.md", "roadmap/**/*.yml", "errors/**/*.md", + "pdf/**/*.md", + "pdf/**/*.yml", "toc.yml", "*.md" ], @@ -69,7 +71,8 @@ "_openGraphImage": "images/social_embed_image.png", "_description": "One framework for creating powerful cross-platform games.", "_appTitle": "MonoGame", - "_enableSearch": true + "_enableSearch": true, + "pdfFooterTemplate": "
MonoGame Documentation
/
" }, "template": [ "default", diff --git a/docfx.json b/docfx.json index ed8f0d3a..fa0f11f1 100644 --- a/docfx.json +++ b/docfx.json @@ -10,6 +10,7 @@ } ], "dest": "api", + "filter": "filterConfig.yml", "includePrivateMembers": false, "disableGitFeatures": false, "disableDefaultFilter": false, @@ -41,6 +42,8 @@ "roadmap/**/*.md", "roadmap/**/*.yml", "errors/**/*.md", + "pdf/**/*.md", + "pdf/**/*.yml", "toc.yml", "*.md" ], @@ -69,7 +72,8 @@ "_openGraphImage": "images/social_embed_image.png", "_description": "One framework for creating powerful cross-platform games.", "_appTitle": "MonoGame", - "_enableSearch": true + "_enableSearch": true, + "pdfFooterTemplate": "
MonoGame Complete Reference GuidePage of
" }, "template": [ "default", diff --git a/filterConfig.yml b/filterConfig.yml new file mode 100644 index 00000000..f5156bae --- /dev/null +++ b/filterConfig.yml @@ -0,0 +1,4 @@ +apiRules: +- exclude: + uidRegex: ^CppNet + type: Namespace diff --git a/pdf/articles/toc.yml b/pdf/articles/toc.yml new file mode 100644 index 00000000..be6ce2e9 --- /dev/null +++ b/pdf/articles/toc.yml @@ -0,0 +1,163 @@ +items: + - name: Introduction + href: ../index.md + - name: Getting Started + href: ../../articles/getting_started/index.md + items: + - name: Setting up MacOS + href: ../../articles/getting_started/1_setting_up_your_os_for_development_macos.md + - name: Setting up Linux + items: + - name: Setting up Arch Linux + href: ../../articles/getting_started/1_setting_up_your_os_for_development_arch.md + - name: Setting up Ubuntu + href: ../../articles/getting_started/1_setting_up_your_os_for_development_ubuntu.md + - name: Setting up Windows + href: ../../articles/getting_started/1_setting_up_your_os_for_development_windows.md + - name: Using Visual Studio + href: ../../articles/getting_started/2_choosing_your_ide_visual_studio.md + - name: Using Rider + href: ../../articles/getting_started/2_choosing_your_ide_rider.md + - name: Using Visual Studio Code + href: ../../articles/getting_started/2_choosing_your_ide_vscode.md + - name: Getting to know MonoGame + href: ../../articles/getting_to_know/index.md + items: + - name: What is + href: ../../articles/getting_to_know/whatis/index.md + items: + - name: Audio + href: ../../articles/getting_to_know/whatis/audio/index.md + - name: Content Pipeline + href: ../../articles/getting_to_know/whatis/content_pipeline/index.md + - name: Graphics + href: ../../articles/getting_to_know/whatis/graphics/index.md + - name: Input + href: ../../articles/getting_to_know/whatis/input/index.md + - name: The Game Loop + href: ../../articles/getting_to_know/whatis/game_loop/index.md + - name: Vector / Matrix / Quaternions + href: ../../articles/getting_to_know/whatis/vector_matrix_quat/index.md + - name: MonoGame Class Library + href: ../../articles/getting_to_know/whatis/monogame_class_library/index.md + - name: How to + href: ../../articles/getting_to_know/howto/index.md + items: + - name: Audio + href: ../../articles/getting_to_know/howto/audio/index.md + - name: Content Pipeline + href: ../../articles/getting_to_know/howto/content_pipeline/index.md + - name: Graphics + href: ../../articles/getting_to_know/howto/graphics/index.md + - name: Input + href: ../../articles/getting_to_know/howto/input/index.md + - name: Advanced Topics + items: + - name: Packaging + href: ../../articles/getting_started/packaging_games.md + - name: Preparing for consoles + href: ../../articles/getting_started/preparing_for_consoles.md + - name: Using Development Nuget Packages + href: ../../articles/getting_started/using_development_nuget_packages.md + - name: Tools + items: + - name: Introduction + href: ../../articles/getting_started/tools/index.md + - name: MGCB + href: ../../articles/getting_started/tools/mgcb.md + - name: MGCB Editor + href: ../../articles/getting_started/tools/mgcb_editor.md + - name: MGFXC + href: ../../articles/getting_started/tools/mgfxc.md + - name: Content Pipeline + items: + - name: Introduction + href: ../../articles/getting_started/content_pipeline/index.md + - name: Why use the Content Pipeline + href: ../../articles/getting_started/content_pipeline/why_content_pipeline.md + - name: Using the Content Builder Project + href: ../../articles/getting_started/content_pipeline/content_builder_project.md + - name: Automating the Content Builder + href: ../../articles/getting_started/content_pipeline/automating_content_builder.md + - name: Using MGCB Editor + href: ../../articles/getting_started/content_pipeline/using_mgcb_editor.md + - name: Custom Effects + href: ../../articles/getting_started/content_pipeline/custom_effects.md + - name: TrueType fonts + href: ../../articles/getting_started/content_pipeline/adding_ttf_fonts.md + - name: Localization + href: ../../articles/getting_started/content_pipeline/localization.md + - name: Migration + items: + - name: Migrating from XNA + href: ../../articles/migration/migrate_xna.md + - name: Migrating from 3.7 + href: ../../articles/migration/migrate_37.md + - name: Upgrading 3.8.x to latest + href: ../../articles/migration/migrate_38.md + - name: Updating Versions + href: ../../articles/migration/updating_versions.md + - name: Tutorials + href: ../../articles/tutorials/index.md + items: + - name: Building 2D Games + href: ../../articles/tutorials/building_2d_games/index.md + items: + - name: "01: What Is MonoGame?" + href: ../../articles/tutorials/building_2d_games/01_what_is_monogame/index.md + - name: "02: Getting Started" + href: ../../articles/tutorials/building_2d_games/02_getting_started/index.md + - name: "03: The Game1 File" + href: ../../articles/tutorials/building_2d_games/03_the_game1_file/index.md + - name: "04: Creating a Class Library" + href: ../../articles/tutorials/building_2d_games/04_creating_a_class_library/index.md + - name: "05: Content Pipeline" + href: ../../articles/tutorials/building_2d_games/05_content_pipeline/index.md + - name: "06: Working with Textures" + href: ../../articles/tutorials/building_2d_games/06_working_with_textures/index.md + - name: "07: Optimizing Texture Rendering" + href: ../../articles/tutorials/building_2d_games/07_optimizing_texture_rendering/index.md + - name: "08: The Sprite Class" + href: ../../articles/tutorials/building_2d_games/08_the_sprite_class/index.md + - name: "09: The AnimatedSprite Class" + href: ../../articles/tutorials/building_2d_games/09_the_animatedsprite_class/index.md + - name: "10: Handling Input" + href: ../../articles/tutorials/building_2d_games/10_handling_input/index.md + - name: "11: Input Management" + href: ../../articles/tutorials/building_2d_games/11_input_management/index.md + - name: "12: Collision Detection" + href: ../../articles/tutorials/building_2d_games/12_collision_detection/index.md + - name: "13: Working With Tilemaps" + href: ../../articles/tutorials/building_2d_games/13_working_with_tilemaps/index.md + - name: "14: Sound Effects and Music" + href: ../../articles/tutorials/building_2d_games/14_soundeffects_and_music/index.md + - name: "15: Audio Controller" + href: ../../articles/tutorials/building_2d_games/15_audio_controller/index.md + - name: "16: Working with SpriteFonts" + href: ../../articles/tutorials/building_2d_games/16_working_with_spritefonts/index.md + - name: "17: Scenes" + href: ../../articles/tutorials/building_2d_games/17_scenes/index.md + - name: "18: Texture Sampling" + href: ../../articles/tutorials/building_2d_games/18_texture_sampling/index.md + - name: "19: User Interface Fundamentals" + href: ../../articles/tutorials/building_2d_games/19_user_interface_fundamentals/index.md + - name: "20: Implementing UI with Gum" + href: ../../articles/tutorials/building_2d_games/20_implementing_ui_with_gum/index.md + - name: "21: Customizing Gum UI" + href: ../../articles/tutorials/building_2d_games/21_customizing_gum_ui/index.md + - name: "22: Snake Game Mechanics" + href: ../../articles/tutorials/building_2d_games/22_snake_game_mechanics/index.md + - name: "23: Completing the Game" + href: ../../articles/tutorials/building_2d_games/23_completing_the_game/index.md + - name: "24: Shaders" + href: ../../articles/tutorials/building_2d_games/24_shaders/index.md + - name: "25: Packaging Your Game for Distribution" + href: ../../articles/tutorials/building_2d_games/25_packaging_game/index.md + - name: "26: Publishing Your Game to itch.io" + href: ../../articles/tutorials/building_2d_games/26_publish_to_itch/index.md + - name: "27: Conclusion and Next Steps" + href: ../../articles/tutorials/building_2d_games/27_conclusion/index.md + - name: Console Access + href: ../../articles/console_access.md + - name: Help and Support + href: ../../articles/help_and_support.md diff --git a/pdf/cover.md b/pdf/cover.md new file mode 100644 index 00000000..7e30af87 --- /dev/null +++ b/pdf/cover.md @@ -0,0 +1,68 @@ +--- +_disableContribution: true +_disableBreadcrumb: true +_disableAffix: true +_disableToc: true +_disableNavbar: true +_disableFooter: true +--- + + + +
+
Complete Reference Guide
+
+ Copyright © 2009-2026 MonoGame Foundation, Inc. +
+
diff --git a/pdf/images/cover.png b/pdf/images/cover.png new file mode 100644 index 00000000..8658d269 Binary files /dev/null and b/pdf/images/cover.png differ diff --git a/pdf/index.md b/pdf/index.md new file mode 100644 index 00000000..f006a3fc --- /dev/null +++ b/pdf/index.md @@ -0,0 +1,28 @@ +--- +title: +description: +--- + +![MonoGame Logo](../images/logo_light.svg) + +Thank you for downloading the MonoGame Complete Reference Guide. We hope it helps you on your game development journey. + +If you would like to help to support the continued development and maintenance of MonoGame please consider donating. + +
+ + Donate + +
+ +--- + +
+ +**© 2009-2026 MonoGame Foundation, Inc. All rights reserved.** + +This document is provided for personal and educational use only. Redistribution, republishing, or commercial distribution of this PDF, in whole or in part, is strictly prohibited without prior written permission from the MonoGame Foundation. + +For the latest documentation, please visit [https://docs.monogame.net](https://docs.monogame.net) + +
diff --git a/pdf/toc.yml b/pdf/toc.yml new file mode 100644 index 00000000..d443f3e3 --- /dev/null +++ b/pdf/toc.yml @@ -0,0 +1,11 @@ +pdf: true +pdfFileName: MonoGameGuide.pdf +pdfTocPage: true +pdfCoverPage: pdf/cover.html +pdfPrintBackground: true +order: 200 +items: +- name: Articles + href: articles/toc.yml +- name: API Reference + href: ../api/toc.yml diff --git a/templates/monogame/public/main.css b/templates/monogame/public/main.css index b76fb87d..3c36ee81 100644 --- a/templates/monogame/public/main.css +++ b/templates/monogame/public/main.css @@ -422,3 +422,168 @@ td > .xref { margin-bottom: 3rem; } } + +/******************************************************************************* +*** Section: Print Styles +*** Styles applied when printing or generating PDF +*******************************************************************************/ + +@media print { + /* Hide site footer in PDF */ + footer, + .footer, + #footer { + display: none !important; + } + + /* Hide navigation elements */ + .navbar, + nav.navbar, + header nav { + display: none !important; + } + + /* Hide sidebar/TOC navigation */ + .toc-offcanvas, + .sidetoc { + display: none !important; + } + + /* Hide contribution/edit buttons */ + .contribution, + .edit-this-page { + display: none !important; + } + + /* Hide video elements */ + video, + iframe[src*="youtube"], + iframe[src*="vimeo"], + .video-container, + .embed-responsive { + display: none !important; + } + + /* Force question-answer elements to be revealed in PDF */ + .question-answer, + .question-answer:not(.revealed) { + color: var(--bs-body-color) !important; + background-color: var(--bs-body-bg) !important; + user-select: auto !important; + } + + .question-answer:not(.revealed)::before { + display: none !important; + } + + .question-answer *, + .question-answer:not(.revealed) * { + opacity: 1 !important; + } + + /* Prevent page breaks inside question-answer blocks */ + .question-answer { + page-break-inside: avoid !important; + break-inside: avoid !important; + } + + /* Prevent page breaks inside paragraphs and common block elements */ + /* Exclude TOC navigation which needs to allow breaks for long lists */ + p, blockquote, .alert { + page-break-inside: avoid !important; + break-inside: avoid !important; + } + + /* Allow page breaks in TOC navigation lists */ + .toc ul, + .toc li, + .toc .nav, + .sidetoc ul, + .sidetoc li { + page-break-inside: auto !important; + break-inside: auto !important; + } + + /* Keep content list items together, but not TOC */ + article ul, + article ol, + article li, + main > ul, + main > l, + main > li { + page-break-inside: avoid !important; + break-inside: avoid !important; + } + + /* Ensure proper page breaks */ + h1, h2, h3, h4 { + page-break-after: avoid; + } + + pre, code, table { + page-break-inside: avoid; + } + + /* Flatten tabs for PDF - show all tab content */ + .tabGroup { + border: none !important; + } + + .tabGroup > ul[role="tablist"] { + display: none !important; + } + + .tabGroup > section, + .tabGroup > .tabpanel, + .tabGroup .tab-pane, + .tabGroup [role="tabpanel"] { + display: block !important; + visibility: visible !important; + opacity: 1 !important; + position: relative !important; + height: auto !important; + overflow: visible !important; + padding: 15px 0 !important; + border-bottom: 1px solid #ddd !important; + margin-bottom: 15px !important; + } + + /* Base label styling for tab panels */ + .tabGroup > section::before, + .tabGroup > .tabpanel::before, + .tabGroup [role="tabpanel"]::before { + display: block; + font-weight: bold; + font-size: 14px; + color: #e73c00; + margin-bottom: 10px; + padding: 5px 10px; + background-color: #f5f5f5; + border-left: 3px solid #e73c00; + } + + /* OS-specific tab labels - scoped to tabGroup */ + .tabGroup [id*="_windows"]::before { content: "Windows" !important; } + .tabGroup [id*="_macos"]::before { content: "macOS" !important; } + .tabGroup [id*="_ubuntu"]::before { content: "Ubuntu" !important; } + .tabGroup [id*="_linux"]:not([id*="_arch"])::before { content: "Linux" !important; } + .tabGroup [id$="_arch"]::before, + .tabGroup [id*="_arch_"]::before { content: "Arch Linux" !important; } + + /* IDE-specific tab labels - scoped to tabGroup */ + .tabGroup [id*="_vscode"]::before { content: "Visual Studio Code" !important; } + .tabGroup [id*="_rider"]::before { content: "JetBrains Rider" !important; } + + /* Other common tab labels - scoped to tabGroup */ + .tabGroup [id*="_csharp"]::before { content: "C#" !important; } + .tabGroup [id*="_opengl"]::before { content: "OpenGL" !important; } + .tabGroup [id*="_directx"]::before { content: "DirectX" !important; } + .tabGroup [id*="_desktopgl"]::before { content: "DesktopGL" !important; } + + /* Remove last border */ + .tabGroup > section:last-child, + .tabGroup > .tabpanel:last-child, + .tabGroup [role="tabpanel"]:last-child { + border-bottom: none !important; + } +}