如何将Redoc文档完整保留格式发布到GitHub Pages

你用默认npx redoc-cli bundle命令丢失格式，是因为该命令默认调用Redoc的默认配置，不会主动读取你之前调整格式时用到的自定义配置项，按以下方案操作即可完整保留格式部署到GitHub Pages：

• 如果你把Redoc的自定义格式配置（主题、侧边栏规则、样式参数等）保存在redocly.yaml等配置文件中，打包时添加--config参数显式指定配置文件即可：
  npx redoc-cli bundle demo/openapi.yaml --config redocly.yaml -o index.html
• 如果你是直接通过命令行参数调整的格式，需要把所有格式参数都同步加到bundle命令中，示例如下：
  npx redoc-cli bundle demo/openapi.yaml --options.theme.colors.primary.main=#2563eb --options.hideLogo=true -o index.html
• 打包完成后先本地打开生成的index.html确认格式符合预期，再将该文件推送到仓库的gh-pages分支根目录，即可完成发布。

该方案可以规避本地环境差异导致的格式异常问题，全程在GitHub服务器完成构建部署：

• 在仓库根目录创建.github/workflows/deploy-docs.yaml文件，写入以下配置，注意替换其中的openapi文件路径、配置文件路径为你自己的实际路径：

该工作流会在你向main分支推送内容时自动触发

name: Deploy Redoc to GitHub Pages
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install redoc-cli
        run: npm install -g redoc-cli
      - name: Build static page with custom config
        run: redoc-cli bundle demo/openapi.yaml --config redocly.yaml -o index.html
      - name: Deploy to gh-pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./
          publish_file: index.html

• 配置提交后，进入仓库Settings-Pages页面，将Pages源设置为gh-pages分支即可。

只要本地打包生成的index.html预览格式符合预期，部署到GitHub Pages后格式会完全一致，无需额外调整。

内容的提问来源于stack exchange，提问作者R.Srivastava