在GitHub Pages部署DocFX遇问题：仅可访问index.html

问题 #

本地执行docfx docfx.json --serve时DocFX文档运行完全正常，但部署到GitHub Pages后仅能访问index.html文件，其余文件无法访问。已严格遵循《DocFX - Quick Start》全部步骤，以下是相关配置文件：

docfx.json #

{
  "$schema": "...docfx.schema.json",
  "metadata": [
    {
      "src": [
        {
          "src": "../ApplicationProgrammingInterface",
          "files": [ "*.csproj" ]
        }
      ],
      "dest": "api"
    }
  ],
  "build": {
    "content": [
      {
        "files": [ "**/*.{md,yml}" ],
        "exclude": [ "_site/**" ]
      }
    ],
    "resource": [ { "files": [ "images/**" ] } ],
    "output": "_site",
    "template": [ "default", "modern" ],
    "globalMetadata": {
      "_appName": "Title",
      "_appTitle": "Title",
      "_enableSearch": true,
      "pdf": true
    }
  }
}

.github/workflows/deploy-docfx.yml #

# Your GitHub workflow file under .github/workflows/
# Trigger the action on push to main
on:
  push:
    branches:
      - main

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  actions: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false
  
jobs:
  publish-docs:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v3
    - name: Dotnet Setup
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 8.x

    - run: dotnet tool update -g docfx
    - run: docfx docs/docfx.json

    - name: Upload artifact
      uses: actions/upload-pages-artifact@v3
      with:
        # Upload entire repository
        path: 'docs/_site'
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4

解决方案 #

1. 配置_baseUrl适配GitHub Pages路径 #

GitHub Pages项目站点（非用户/组织站点）的根路径为https://<用户名>.github.io/<仓库名>/，而DocFX默认生成的资源链接为绝对路径，会指向域名根目录，导致无法找到文件。需在docfx.json的globalMetadata中添加_baseUrl字段，值为你的仓库名称（前缀加斜杠）：

修改后的globalMetadata片段：

"globalMetadata": {
  "_appName": "Title",
  "_appTitle": "Title",
  "_enableSearch": true,
  "pdf": true,
  "_baseUrl": "/你的仓库名称"
}

2. 验证DocFX构建路径 #

确保workflow中的docfx命令正确指向配置文件位置。当前命令docfx docs/docfx.json会自动执行metadata生成和文档构建，若你的docfx.json确实在docs目录下则无需修改；若路径有误，需调整命令中的路径参数。

3. 确认GitHub Pages部署配置 #

检查GitHub仓库的Pages设置，确保部署来源选择为GitHub Actions，此配置已在你的workflow中通过actions/deploy-pages实现，无需额外调整。

内容的提问来源于stack exchange，提问作者szpycio