Fix the missing API Reference Table of Contents

.github/workflows/main.yml

@@ -42,17 +42,24 @@ jobs:
       - name: Restore dotnet tools
         run: dotnet tool restore
 
+      - name: Run Metadata Build
+        run: dotnet docfx metadata ci.docfx.json
+
       - name: Run Build
-        run: dotnet docfx ci.docfx.json
+        run: dotnet docfx build ci.docfx.json
+
+      - name: Create PDF build folder
+        run: |
+          mkdir -p _pdf
 
       - name: Generate PDF
-        run: dotnet docfx pdf ci.docfx.json
+        run: dotnet docfx pdf docfx.pdf.json --output _pdf
 
       - name: Copy PDF to downloads and clean up
         run: |
           mkdir -p _site/downloads
-          cp _site/pdf/MonoGameGuide.pdf _site/downloads/
-          rm -rf _site/pdf
+          cp _pdf/pdf/MonoGameGuide.pdf _site/downloads/
+          rm -rf _pdf
 
       - name: Setup Pages
         uses: actions/configure-pages@v5

build.ps1

@@ -19,16 +19,22 @@ if (-not (Test-Path $FrameworkDll) -or -not (Test-Path $PipelineDll)) {
 
 # Build documentation
 Write-Host "Building DocFx..." -ForegroundColor Green
-dotnet docfx docfx.json
+dotnet docfx metadata docfx.json
 
-# Generate PDF
+# Build documentation
+Write-Host "Building DocFx..." -ForegroundColor Green
+dotnet docfx build docfx.json
+
+New-Item -ItemType Directory -Force -Path "_pdf" | Out-Null
+
+# Generate PDF (using PDF-specific config that includes pdf/** files)
 Write-Host "Generating PDF..." -ForegroundColor Green
-dotnet docfx pdf docfx.json
+dotnet docfx pdf docfx.pdf.json --output _pdf
 
 # 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
+Copy-Item "_pdf/pdf/MonoGameGuide.pdf" "_site/downloads/"
+Remove-Item -Path "_pdf" -Recurse -Force
 
 Write-Host "Build and documentation generation completed successfully!" -ForegroundColor Green

build.sh

@@ -17,18 +17,25 @@ if [ ! -f "$FRAMEWORK_DLL" ] || [ ! -f "$PIPELINE_DLL" ]; then
     dotnet build external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj -p:DisableNativeBuild=true
 fi
 
+# Build documentation
+echo "Building DocFx..."
+dotnet docfx metadata docfx.json
+
 # Build documentation
 echo "Building DocFx..."
 dotnet docfx docfx.json
 
-# Generate PDF
+mkdir -p _pdf
+
+# Generate PDF (using PDF-specific config that includes pdf/** files)
 echo "Generating PDF..."
-dotnet docfx pdf docfx.json
+dotnet docfx build docfx.pdf.json --output _pdf
+dotnet docfx pdf docfx.pdf.json --output _pdf
 
 # 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
+cp _pdf/pdf/MonoGameGuide.pdf _site/downloads/
+rm -rf _pdf
 
 echo "Build and documentation generation completed successfully!"

docfx.json

@@ -42,8 +42,6 @@
           "roadmap/**/*.md",
           "roadmap/**/*.yml",
           "errors/**/*.md",
-          "pdf/**/*.md",
-          "pdf/**/*.yml",
           "toc.yml",
           "*.md"
         ],

docfx.pdf.json

@@ -0,0 +1,100 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": [
+            "external/MonoGame/Artifacts/MonoGame.Framework/DesktopGL/Debug/MonoGame.Framework.dll",
+            "external/MonoGame/Artifacts/MonoGame.Framework.Content.Pipeline/Debug/MonoGame.Framework.Content.Pipeline.dll"
+          ]
+        }
+      ],
+      "dest": "api",
+      "filter": "filterConfig.yml",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
+      "EnumSortOrder": "alphabetic"
+    }
+  ],
+  "rules": {
+    "InvalidFileLink": "error",
+    "InvalidBookmark": "error",
+    "UidNotFound": "error",
+    "ReferencedXrefPropertyNotString": "error"
+  },  
+  "build": {
+    "content": [
+      {
+        "files": [
+          "api/**/*.yml",
+          "api/**/*.md"
+        ]
+      },
+      {
+        "files": [
+          "articles/**/*.md",
+          "articles/**/*.yml",
+          "foundation/**/*.md",
+          "roadmap/**/*.md",
+          "roadmap/**/*.yml",
+          "errors/**/*.md",
+          "pdf/**/*.md",
+          "pdf/**/*.yml",
+          "toc.yml",
+          "*.md"
+        ],
+        "exclude": [ "_site/**", "README.md" ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "**/images/**",
+          "**/videos/**",
+          "**/files/**",
+          "**/snippets/**",
+          "**/*.docx",
+          "CNAME"
+        ]
+      }
+    ],
+    "output": "_site",
+    "globalMetadata": {
+      "_appLogoUrl": "https://monogame.net",
+      "_appFaviconPath": "/images/favicon.png",
+      "_disableBreadcrumb": "true",
+      "_appFooter": "Copyright © 2009-2026 MonoGame Foundation, Inc.",
+      "_hostname": "monogame.net",
+      "_openGraphImage": "images/social_embed_image.png",
+      "_description": "One framework for creating powerful cross-platform games.",
+      "_appTitle": "MonoGame",
+      "_enableSearch": true,
+      "pdfFooterTemplate": "<div style='width: 100%; font-size: 11px; font-family: Segoe UI, Tahoma, Geneva, Verdana, sans-serif; border-top: 2px solid #e73c00; padding: 8px 20px 0 20px; display: flex; justify-content: space-between; align-items: center;'><span style='color: #e73c00; font-weight: 600;'>MonoGame Complete Reference Guide</span><span style='color: #666;'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></span></div>"
+    },
+    "template": [
+      "default",
+      "modern",
+      "templates/monogame"
+    ],
+    "markdownEngineProperties": {
+      "markdigExtensions": [
+        "Abbreviations",
+        "Figures",
+        "CustomContainers",
+        "attributes"
+      ]
+    },
+    "postProcessors": [],
+    "keepFileLink": false,
+    "disableGitFeatures": false,
+    "sitemap": {
+      "baseUrl": "https://docs.monogame.net/",
+      "priority": 0.1,
+      "changefreq": "monthly"
+    }    
+  }
+}

serve.ps1

@@ -5,4 +5,4 @@ $ErrorActionPreference = "Stop"
 .\build.ps1
 
 # Start DocFx serve
-dotnet docfx docfx.json --serve
+dotnet docfx serve .\_site

serve.sh

@@ -6,4 +6,4 @@ set -e
 ./build.sh
 
 # Start DocFx serve
-dotnet docfx docfx.json --serve
+dotnet docfx serve _site