MkDocs 插件：翻译与智能问答

在使用 MkDocs 编写技术文档时，如果你需要多语言支持或智能交互功能，这两个插件能帮上大忙。它们操作简单、配置灵活，能显著提升文档的实用性和用户体验。

一、mkdocs-translate：一键实现文档多语言翻译

适用场景：需要将英文文档翻译成中文、法语等其他语言，或维护多语言版本的项目文档。

核心功能

  • 基于 DeepL/OpenAI 等 API 自动翻译文档内容
  • 保留原有文档结构和 Markdown 格式
  • 支持增量翻译（仅更新修改部分）
  • 可配置多个目标语言

安装与配置

# 安装插件
pip install mkdocs-translate

在 mkdocs.yml 中添加配置（以 DeepL 为例）：

plugins:
  - translate:
      api_provider: deepl    # 可选 deepl 或 openai
      api_key: your_deepl_key  # 替换为你的 API 密钥
      target_languages:       # 目标语言列表
        - zh                  # 中文
        - fr                  # 法语

使用示例

  1. 编写英文源文档（docs/index.md）： 
    # Welcome to My Project
This is a sample documentation page.
  2. 执行翻译命令： 
    mkdocs translate
  3. 生成的中文文档位于 site/zh/ 目录，内容自动翻译为： 
    # 欢迎来到我的项目
这是一个示例文档页面。

二、mkdocs-chatgpt：为文档添加智能问答

适用场景：希望用户能通过对话快速获取文档中的信息，或解答常见问题。

核心功能

  • 在文档中嵌入 ChatGPT 对话窗口
  • 自动关联文档内容生成回答
  • 支持自定义提示词模板
  • 可配置 API 密钥和模型参数

安装与配置

# 安装插件
pip install mkdocs-chatgpt

在 mkdocs.yml 中配置：

plugins:
  - chatgpt:
      api_key: your_openai_key  # 替换为你的 OpenAI API 密钥
      prompt_template: "根据文档内容回答：{question}"  # 自定义提问模板

使用示例

  1. 在文档中添加对话组件（docs/faq.md）： ```markdown

    常见问题解答


2. 构建并运行文档：
```bash
mkdocs serve
  1. 用户访问页面时可直接输入问题，例如：“如何安装插件？”，插件会结合文档内容生成回答。

三、注意事项

  1. API 密钥安全：
    避免将密钥直接写入配置文件，建议通过环境变量读取： ```yaml plugins:
    • translate: api_key: ${DEEPL_API_KEY} # 从环境变量获取 ```

  2. 成本控制：
    翻译和对话功能会消耗 API 额度，建议在开发环境测试后再部署到生产环境。

  3. 网络要求：
    两个插件均需联网调用外部 API，若网络受限可配置代理或使用本地模型（需自定义适配）。

总结

  • mkdocs-translate 让多语言文档维护变得轻松，适合国际化项目。
  • mkdocs-chatgpt 通过智能交互提升用户体验，尤其适合复杂文档的导航。
    两者结合使用，能让你的 MkDocs 文档更具专业性和易用性。试试吧！