跳转至

为MKdocs添加AI摘要(Plus版本)

MkDocs Plugins AI Powered Python 3.8+

中文 | English

🚀 您的MkDocs文档首选智能摘要！
这个项目利用MkDocs hooks，为您的技术文档和博客添加AI驱动的摘要生成和智能阅读统计功能。

预览图1 预览图2

🌟 为什么选择这个插件？

  • 🤖 多 AI 服务支持 - 支持 DeepSeek、OpenAI、Google Gemini、GLM 等主流 AI 服务
  • ⚡ 智能缓存系统 - 避免重复 API 调用，大幅提升构建速度
  • 🌍 多语言支持 - 支持中英文等多种语言，页面级语言控制
  • 🔄 自动降级机制 - 主服务不可用时自动切换备用服务，确保稳定性
  • 🚀 CI/CD 友好 - 专为持续集成环境优化，支持缓存策略
  • 🎨 完美兼容 - 与所有 MkDocs 主题无缝集成

安装

从 PyPI 安装（推荐）

Bash
1
pip install mkdocs-ai-summary-wcowin

快速开始

1. 基本配置

在 mkdocs.yml 中添加插件：

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
plugins:
  - ai-summary:
      ai_service: "glm"          # 推荐使用GLM
      # local_enabled: true             # 本地环境启用

!!! abstract "⚡ AI摘要 (GLM)"

    为MKdocs添加AI摘要(Plus版本)是一款利用AI技术为MkDocs文档生成智能摘要的插件。支持多种AI服务，具备智能缓存、多语言支持、自动降级机制等特点，易于安装和配置，与MkDocs主题完美兼容。

      enabled_folders:
        - docs                       # 处理 docs 文件夹
      exclude_patterns:
        - index.md                    # 排除 index.md 文件

2. 获取 API 密钥

推荐使用 GLM（性价比最高）： 1. 访问 GLM 开放平台 2. 注册并创建 API 密钥 3. 在项目根目录创建 .env 文件：

Text Only
1
GLM_API_KEY=your_api_key_here

3. 构建文档

Bash
1
2
mkdocs build  # 构建文档
mkdocs serve  # 本地预览

现在开始，您的文档页面顶部会自动显示 AI 生成的摘要！

高级配置

完整配置示例

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
plugins:
  - ai-summary:
      ai_service: "glm"          # 主要 AI 服务
      fallback_services:               # 备用服务
        - "openai"
        - "gemini"
      summary_language: "zh"           # 摘要语言 (zh/en/both)
      local_enabled: true              # 本地环境启用
      enabled_folders:
        - docs
        - blog
      exclude_patterns:
        - tags.md                # 排除 tags.md 文件
        - blog/posts/**
        - blog/archive/**

多 AI 服务配置

在 .env 文件中配置多个服务作为备用：

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 主要服务

!!! tip "📖 阅读信息"
    :material-clock-time-two-outline:阅读时间：**3** 分钟 | :material-circle-edit-outline:中文字符：**1178** | :fontawesome-solid-code:有效代码行数：**182**


GLM_API_KEY=your_deepseek_key

# 备用服务
OPENAI_API_KEY=your_openai_key
GEMINI_API_KEY=your_gemini_key
DEEPSEEK_API_KEY=your_glm_key

配置指南

页面级语言控制

在页面的 front matter 中指定摘要语言：

Markdown
1
2
3
4
5
6
---
title: 我的文档
ai_summary_lang: en  # 为这个页面生成英文摘要
---

# 页面内容

核心配置选项

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
plugins:
  - ai-summary:
      # AI 服务设置
      ai_service: "deepseek"          # 主要服务
      fallback_services: ["openai"]   # 备用服务

      # 语言与内容
      summary_language: "zh"          # zh/en/both
      max_content_length: 8000         # 内容长度限制

      # 文件选择
      enabled_folders: ["docs"]       # 处理的文件夹
      exclude_patterns: ["**/api/**"] # 排除模式

      # 性能相关
      cache_enabled: true              # 启用缓存
      local_enabled: true              # 本地环境启用

本地开发配置

步骤1：获取API密钥

根据您选择的AI服务，获取相应的API密钥：

DeepSeek (推荐) 1. 访问 DeepSeek官网 2. 注册账号并登录 3. 进入API管理页面 4. 创建新的API密钥 5. 复制密钥备用

OpenAI 1. 访问 OpenAI Platform 2. 登录您的账号 3. 进入API Keys页面 4. 点击"Create new secret key" 5. 复制密钥备用

Google Gemini 1. 访问 Google AI Studio 2. 登录Google账号 3. 创建新的API密钥 4. 复制密钥备用

GLM (智谱AI)(最推荐) 1. 访问 智谱AI开放平台 2. 注册并登录账号 3. 进入API管理 4. 创建API密钥 5. 复制密钥备用

步骤2：创建.env文件

在您的项目根目录（与mkdocs.yml同级）创建.env文件：

Bash
1
2
# 在项目根目录执行
touch .env

步骤3：配置API密钥

编辑.env文件，添加您的API密钥：

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# DeepSeek API密钥 (推荐)
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# OpenAI API密钥
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Google Gemini API密钥
GEMINI_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# GLM API密钥
GLM_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxx

# 可选：调试模式
AI_SUMMARY_DEBUG=false

# 可选：API超时设置（秒）
AI_SUMMARY_TIMEOUT=30

# 可选：最大重试次数
AI_SUMMARY_MAX_RETRIES=3

重要提示： - 只需要配置您计划使用的AI服务的API密钥 - 确保.env文件已添加到.gitignore中，避免泄露API密钥 - API密钥格式因服务而异，请确保复制完整的密钥

步骤4：验证配置

运行以下命令验证配置是否正确：

Bash
1
2
3
4
5
# 本地构建测试
mkdocs build

# 本地预览
mkdocs serve

如果配置正确，您应该能看到插件成功加载并生成AI摘要。

GitHub部署配置

1. 添加 API 密钥到 GitHub Secrets

在您的 GitHub 仓库中： 1. 进入 Settings → Secrets and variables → Actions 2. 添加新的 secret：DEEPSEEK_API_KEY 3. 将您的 API 密钥粘贴进去

2. 配置 GitHub Actions 工作流

方案 A：创建新的工作流

创建 .github/workflows/ci.yml 文件：

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
name: ci
on:
  push:
    branches: [main, master]
  pull_request:
    types: [closed]
    branches: [main, master]

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          sparse-checkout: |
            docs
            includes
            requirements.txt
            .ai_cache

      - uses: actions/setup-python@v4
        with:
          python-version: 3.x

      - name: 设置缓存 ID
        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV

      - uses: actions/cache@v3
        with:
          key: mkdocs-material-${{ github.run_number }}
          path: .cache
          restore-keys: |
            mkdocs-material-

      # 安装您现有的依赖
      - run: pip install mkdocs-material
      - run: pip install mkdocs-ai-summary-wcowin

      # 使用 AI 摘要部署
      - name: 使用 AI 摘要部署
        env:
          AI_SUMMARY_CI_ENABLED: 'true'
          AI_SUMMARY_CACHE_ENABLED: 'true'
          AI_SUMMARY_CACHE_EXPIRE_DAYS: '300'
          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
        run: mkdocs gh-deploy --force

      # 自动提交 AI 缓存文件
      - name: 自动提交 AI 缓存
        run: |
          if [ -d ".ai_cache" ] && [ "$(ls -A .ai_cache 2>/dev/null)" ]; then
            git config --local user.email "action@github.com"
            git config --local user.name "GitHub Action"
            git add .ai_cache/
            if ! git diff --cached --quiet; then
              git commit -m "🤖 自动更新 AI 摘要缓存 [skip ci]"
              git push
            fi
          fi
方案 B：在现有工作流中添加

如果您已经有 ci.yml 文件，请在现有工作流中添加以下步骤：

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 在现有的依赖安装部分添加
- run: pip install mkdocs-ai-summary-wcowin

# 替换您的 mkdocs 构建/部署步骤为：
- name: 使用 AI 摘要部署
  env:
    AI_SUMMARY_CI_ENABLED: 'true'
    AI_SUMMARY_CACHE_ENABLED: 'true'
    GLM_API_KEY: ${{ secrets.GLM_API_KEY }}
  run: mkdocs gh-deploy --force

# 在部署后添加（可选 - 用于缓存管理）
- name: 自动提交 AI 缓存
  run: |
    if [ -d ".ai_cache" ] && [ "$(ls -A .ai_cache 2>/dev/null)" ]; then
      git config --local user.email "action@github.com"
      git config --local user.name "GitHub Action"
      git add .ai_cache/
      if ! git diff --cached --quiet; then
        git commit -m "🤖 自动更新 AI 摘要缓存 [skip ci]"
        git push
      fi
    fi

现有工作流集成详细步骤

如果您已经有一个正常工作的 ci.yml 文件，请按照以下步骤添加 AI 摘要功能：

步骤 1：添加插件安装

在您现有的依赖安装部分添加这一行：

YAML
1
- run: pip install mkdocs-ai-summary-wcowin

步骤 2：添加 API 密钥到环境变量

更新您的 mkdocs 构建/部署步骤，包含 API 密钥：

YAML
1
2
3
4
- name: 部署文档
  env:
    DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}  # 添加这一行
  run: mkdocs gh-deploy --force

步骤 3：配置 AI 摘要设置（可选）

为了更好的 CI 性能，添加这些环境变量：

YAML
1
2
3
4
5
env:
  AI_SUMMARY_CI_ENABLED: 'true'        # 在 CI 中启用
  AI_SUMMARY_CACHE_ENABLED: 'true'     # 使用缓存
  AI_SUMMARY_CACHE_EXPIRE_DAYS: '300'  # 缓存 300 天
  DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}

步骤 4：添加缓存管理（推荐/可选）

要自动提交生成的缓存文件，在部署后添加此步骤：

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
- name: 自动提交 AI 缓存
  run: |
    if [ -d ".ai_cache" ] && [ "$(ls -A .ai_cache 2>/dev/null)" ]; then
      git config --local user.email "action@github.com"
      git config --local user.name "GitHub Action"
      git add .ai_cache/
      if ! git diff --cached --quiet; then
        git commit -m "🤖 自动更新 AI 摘要缓存 [skip ci]"
        git push
      fi
    fi

4. 启用 GitHub Pages

在仓库设置中启用 GitHub Pages，选择 gh-pages 分支作为源。

提示与故障排除

缓存管理

插件会自动缓存生成的摘要，避免重复 API 调用：

YAML
1
2
3
4
5
plugins:
  - ai-summary:
      cache_enabled: true              # 启用缓存
      cache_expire_days: 30            # 缓存30天
      clear_cache: false               # 保留现有缓存

多 AI 服务配置

配置主服务和备用服务，确保稳定性：

YAML
1
2
3
4
5
6
plugins:
  - ai-summary:
      ai_service: "deepseek"          # 主服务
      fallback_services:               # 备用服务
        - "openai"
        - "gemini"

常见问题

Q: 插件不生成摘要？ - 检查 API 密钥配置 - 确保 local_enabled: true（本地开发） - 验证文件在 enabled_folders 中

Q: CI 构建失败？ - 确认 GitHub Secrets 中已添加 API 密钥 - 检查工作流文件中的环境变量名称 - 确保插件已在工作流中安装

Q: 如何清除缓存？ - 配置中设置 clear_cache: true - 或手动删除 .ai_cache/ 目录

支持与贡献

支持

贡献代码

我们欢迎各种形式的贡献： - 🐛 报告 Bug - 💡 提出新功能建议 - 📝 改进文档 - 🔧 提交代码

常见问题

Q: 插件不生成摘要？ - 检查 API 密钥配置 - 确保 local_enabled: true（本地开发） - 验证文件在 enabled_folders 中

Q: CI 构建失败？ - 确认 GitHub Secrets 中已添加 API 密钥 - 检查工作流文件中的环境变量名称 - 确保插件已在工作流中安装

Q: 如何清除缓存？ - 配置中设置 clear_cache: true - 或手动删除 .ai_cache/ 目录

许可证

本项目采用 MIT 许可证

致谢

  • MkDocs - 本插件扩展的静态站点生成器
  • MkDocs Material - 启发我们设计的美观主题
  • 所有使这个插件成为可能的 AI 服务提供商

🔗 联系作者

Telegram

Telegram

微信交流

⭐ 项目统计

Star History Chart

Stars Forks

☕ 支持项目

如果这个项目对您有帮助，请给它一个 ⭐ Star！

用 ❤️ 为 MkDocs 社区制作

📚 相关文章推荐

💬 评论

评论系统加载中...