跳转至

好的，根据我们之前的对话，这份详细的指南将帮助你为 MkDocs 网站集成 GitHub 仓库的星标 (Stars) 和 Fork 数量显示功能。

仓库链接：详细指南⚓︎

MkDocs 网站集成 GitHub 星标与 Fork 数量显示

本指南将详细介绍如何为您的 MkDocs 网站集成 GitHub 仓库的星标 (Stars) 和 Fork 数量显示功能。此功能由 Material for MkDocs 主题提供，它通过调用 GitHub API 来获取这些公开数据。为了避免匿名 API 请求的速率限制，并确保稳定获取数据，我们需要使用一个 GitHub Personal Access Token (PAT)。

我们将使用一个权限最小化且无有效期的 PAT，并通过 GitHub Actions 的 Secret 机制安全地管理它。

前提条件⚓︎

在开始之前，请确保您已满足以下条件：

  • 已有一个基于 MkDocs 和 Material for MkDocs 主题搭建的 GitHub Pages 网站。
  • 已配置 GitHub Actions 工作流 (.github/workflows/deploy.yml) 用于部署网站。
  • 了解基本的 GitHub 操作和 YAML 语法。

创建 PAT⚓︎

我们将创建一个专门用于获取公开仓库信息的 PAT，它将拥有最低的权限。

  1. 访问 GitHub PAT 创建页面：

    • 登录您的 GitHub 账号。
    • 点击右上角的头像，选择 Settings (设置)。
    • 在左侧导航栏中，滚动到底部，找到 Developer settings (开发者设置)。
    • 点击 Personal access tokens (个人访问令牌) -> Tokens (classic) (经典令牌)。
    • 点击右上角的 Generate new token (classic) (生成新令牌 (经典))。

  2. 配置 PAT 详情：

    • Note (备注)： 填写一个易于识别的名称，例如 MKDOCS_BUILD。这将帮助您记住此令牌的用途。
    • Expiration (有效期)： 务必选择 No expiration (无有效期)。
      • 解释： 由于此 PAT 仅用于读取公开数据，且不具备任何修改权限，将其设置为无有效期可以避免您频繁手动更新令牌的麻烦，同时风险极低。
    • Select scopes (选择权限)： 不要勾选任何权限 (No scopes)。
      • 解释： Material for MkDocs 只需要读取公开仓库的星标和 Fork 数量，这些信息是公开的。PAT 的作用主要是为了提高 GitHub API 的速率限制（从匿名用户的 60 请求/小时提升到认证用户的 5000 请求/小时），而不是为了访问私有数据。因此，不勾选任何权限是最安全且完全足够的配置。

  3. 生成并复制 PAT：

    • 点击页面底部的 Generate token (生成令牌) 按钮。
    • 重要： 生成的令牌只会显示一次！请务必立即复制此令牌字符串，并妥善保管。一旦离开此页面，您将无法再次看到它。

将 PAT 添加到 GitHub 仓库 Secrets⚓︎

为了安全地在 GitHub Actions 工作流中使用您的 PAT，我们将其存储为仓库 Secret。这样，令牌就不会直接暴露在您的代码中。

  1. 导航到仓库 Secrets：

    • 打开您的 MkDocs 网站所在的 GitHub 仓库页面。
    • 点击顶部的 Settings (设置) 选项卡。
    • 在左侧导航栏中，找到 Secrets and variables (密钥和变量) -> Actions。
    • 点击 New repository secret (新建仓库密钥)。

  2. 添加 Secret：

    • Name (名称)： 填写 MKDOCS_BUILD_TOKEN。
      • 提示： 这个名称是您在 GitHub Actions 工作流中引用此令牌的键。建议使用一个清晰且与用途相关的名称。
    • Secret (值)： 将您在步骤一中复制的 PAT 粘贴到此处。
    • 点击 Add secret (添加密钥)。

现在，您的 PAT 已安全地存储在仓库 Secret 中，并且可以在 GitHub Actions 工作流中被引用。

修改 GitHub Actions 工作流文件⚓︎

我们需要修改您的部署工作流，使其在构建 MkDocs 网站时能够访问到这个 PAT。

  1. 打开 deploy.yml 文件：

    • 在您的 GitHub 仓库中，导航到 .github/workflows/deploy.yml 文件。
    • 点击编辑按钮（通常是铅笔图标）/ 在文件资源管理器中导航到`deploy.yml后右键进行编辑。

  2. 添加环境变量：

    • 找到您的 Build 步骤（通常是执行 mkdocs build 命令的步骤）。
    • 在该步骤下添加一个 env 块，并引用您在步骤二中创建的 Secret。

    请将您的 deploy.yml 文件中 Build 步骤修改为以下内容：

    ```yaml

    ... (文件顶部其他内容保持不变) ...⚓︎

约 1811 个字 41 行代码 预计阅读时间 10 分钟

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
jobs:
  deploy:
    # ... (deploy job 的其他配置保持不变) ...

    steps:
      # ... (前面的步骤，如 Checkout, Set up Python, Install dependencies 保持不变) ...

      # 步骤 4: 构建 MkDocs 网站。
      # 这将在工作流程的运行器中生成 'site' 文件夹，包含所有静态网站文件。
      - name: Build # 步骤名称
        run: mkdocs build
        env: # <-- 在这里添加 env 块
          # 引用你之前在仓库 Secrets 中设置的 PAT
          # 确保这里的 'MKDOCS_BUILD_TOKEN' 与你在 GitHub 仓库 Settings -> Secrets and variables -> Actions 中设置的 Secret 名称完全一致。
          MKDOCS_MATERIAL_GITHUB_TOKEN: ${{ secrets.MKDOCS_BUILD_TOKEN }}

      # ... (后面的步骤，如 Setup Pages, Upload artifact, Deploy to GitHub Pages 保持不变) ...
```

**代码解析：**
*   **`env:`**：这是一个 YAML 关键字，用于定义当前步骤的环境变量。
*   **`MKDOCS_MATERIAL_GITHUB_TOKEN:`**：这是 Material for MkDocs 主题在构建时会查找的环境变量名称，用于获取 GitHub API 令牌。
*   **`${{ secrets.MKDOCS_BUILD_TOKEN }}`**：这是 GitHub Actions 的语法，表示从您的仓库 Secrets 中获取名为 `MKDOCS_BUILD_TOKEN` 的值。GitHub Actions 会在运行时自动将 Secret 的值注入到环境变量中，而不会将其暴露在日志或代码中。
  1. 提交更改：
    • 保存并提交对 deploy.yml 文件的更改。

配置 mkdocs.yml⚓︎

最后，您需要在 MkDocs 的配置文件中启用星标和 Fork 数量显示功能。

  1. 打开 mkdocs.yml 文件：

    • 在您的仓库根目录找到 mkdocs.yml 文件并打开编辑。

  2. 添加或修改 extra.repo_stats 配置：

    • 在 mkdocs.yml 中，找到 theme 和 extra 部分。
    • 确保 theme.name 是 material。
    • 在 extra 部分，添加或修改 repo 和 repo_stats 配置；在site_description:下增加两行配置，如下所示：
    YAML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
    # mkdocs.yml
site_description: xxx

# 以下两行用于在页眉显示GitHub仓库链接
repo_url: https://github.com/Muchili-code/muchili-code.github.io # 替换为你的博客仓库的实际URL
repo_name: Muchili/Blog # 可选：自定义显示的仓库名称，例如 "你的GitHub用户名/你的博客仓库名"

theme:
  name: material
  features:
    - navigation.footer # 示例：如果您想在页脚显示统计信息，可能需要此功能
  # ... 其他主题配置，如 palette, font 等

extra:
  # ... 其他 extra 配置，如 social, analytics 等
  repo:
    provider: github
    host: github.com
    user: your-github-username # <-- 替换为您的 GitHub 用户名
    name: your-repository-name # <-- 替换为您的 MkDocs 仓库名称
  # 上面四行可省略
  repo_stats: true # <-- 启用星标和 Fork 数量显示

    配置解析： * extra.repo.user：您的 GitHub 用户名。 * extra.repo.name：您的 MkDocs 网站所在的 GitHub 仓库名称。 * extra.repo_stats: true：这是启用星标和 Fork 数量显示的关键配置。

  3. 提交更改：

    • 保存并提交对 mkdocs.yml 文件的更改。

验证与测试⚓︎

完成以上所有步骤后，您的 GitHub Pages 网站应该能够显示星标和 Fork 数量了。

  1. 触发部署：

    • 由于您对 deploy.yml 和 mkdocs.yml 进行了更改，GitHub Actions 工作流应该会自动触发一次部署（如果您配置了 on: push）。
    • 您也可以手动从 GitHub 仓库的 Actions 选项卡中运行 Deploy MkDocs site to Pages with Submodules 工作流。

  2. 检查 GitHub Actions 运行：

    • 在您的 GitHub 仓库中，点击 Actions 选项卡。
    • 找到最新的工作流运行，并确保它成功完成。

  3. 访问您的网站：

    • 部署成功后，访问您的 GitHub Pages 网站 URL。
    • 检查网站的页脚或侧边栏（具体位置取决于您的 Material for MkDocs 主题配置），您应该能看到您的 GitHub 仓库的星标和 Fork 数量。

重要提示⚓︎

  • 权限最小化： 再次强调，您创建的 PAT 没有任何敏感权限，这大大降低了即使 PAT 泄露时的风险。
  • PAT 安全： 永远不要将 PAT 直接写入任何公开可见的文件（如 mkdocs.yml 或 deploy.yml）。始终使用 GitHub Secrets 来管理敏感信息。
  • 速率限制： PAT 的主要作用是提高 GitHub API 的请求速率限制，确保您的网站在频繁访问时也能稳定获取数据。
  • 故障排除： 如果星标和 Fork 数量没有显示，请检查以下几点：
    • GitHub Actions 运行是否成功，是否有任何错误日志。
    • MKDOCS_BUILD_TOKEN Secret 的名称是否与 deploy.yml 中引用的名称完全一致。
    • mkdocs.yml 中 extra.repo.user 和 extra.repo.name 是否正确指向您的 GitHub 仓库。
    • 您的网络连接是否正常。

通过以上详细步骤，您已成功为您的 MkDocs 网站配置了 GitHub 星标和 Fork 数量显示功能，并确保了部署过程的安全性和稳定性。