MkDocs 配置详解与使用教程

本文档旨在为您详细讲解 MkDocs 的使用流程和 mkdocs.yml 配置文件的各个参数。

一、MkDocs 使用教程 (完整流程)

MkDocs 是一个快速、简单、功能强大的静态网站生成器，专为项目文档设计。它使用 Markdown 格式编写文档，并将其转换为美观的静态网站。

1.1 安装 MkDocs

首先，确保您的系统安装了 Python 和 pip。然后，打开终端（如 PowerShell 或命令提示符）运行以下命令来安装 MkDocs 和推荐的 Material for MkDocs 主题：

pip install mkdocs mkdocs-material

1.2 创建 MkDocs 项目

要创建一个新的 MkDocs 项目，请导航到您希望创建项目的目录（例如，您的项目文件夹 G:\\AD元件库\\XR-GRJ-001）。然后运行：

mkdocs new .

这个命令会在当前目录（. 表示当前目录）生成一个基本的 MkDocs 项目结构：

• mkdocs.yml：主配置文件。
• docs/：默认的文档存放目录（如果您的文档在其他目录，需要修改 mkdocs.yml 中的 docs_dir）。

注意： 在我们当前的案例中，您的文档在 Markdown/ 目录下，所以我们需要手动创建或调整 mkdocs.yml。

1.3 文档编写

使用您喜欢的 Markdown 编辑器（如 Typora, VS Code）在您的文档目录（例如 G:\\AD元件库\\XR-GRJ-001\\Markdown\\）中创建或编辑 Markdown 文件（.md）。

关键点：图片引用
确保图片使用相对路径引用。如果图片和 Markdown 文件在同一个目录下的 picture 子目录中，引用方式应为：

![图片描述](picture/您的图片名.jpg "可选的图片标题")

绝对不要使用 file:/// 开头的本地绝对路径。

1.4 启动本地服务器 (实时预览)

在 MkDocs 项目的根目录（即 mkdocs.yml 文件所在的目录，在您的案例中是 G:\\AD元件库\\XR-GRJ-001）运行以下命令：

mkdocs serve

MkDocs 将启动一个本地开发服务器，通常在 http://127.0.0.1:8000/。您可以在浏览器中打开这个地址，实时预览文档。当您修改 Markdown 文件或 mkdocs.yml 文件时，浏览器会自动刷新。

1.5 构建静态网站 (生成可部署的文件)

当您完成文档编写并希望将其部署到服务器时，您需要构建静态网站。在 MkDocs 项目的根目录运行：

mkdocs build

这个命令会在项目根目录下创建一个名为 site/ 的文件夹。site/ 文件夹包含了您完整的静态网站，所有 HTML、CSS、JavaScript 和图片文件都在其中。

1.6 部署到服务器 (例如 IIS)

site/ 文件夹中的内容是纯静态的，可以直接部署到任何 Web 服务器上（如 IIS, Nginx, Apache 等）。

1. 复制 site/ 文件夹内容： 将 G:\\AD元件库\\XR-GRJ-001\\site 文件夹内部的所有文件和子文件夹（而不是 site 文件夹本身）复制到您的 IIS 网站的物理路径根目录。
2. 配置 IIS (如果需要)： 确保 IIS 网站的物理路径正确指向您复制文件的地方，并且 IIS 进程拥有读取这些文件的权限。

---

二、mkdocs.yml 配置参数详解

mkdocs.yml 是 MkDocs 的核心配置文件，使用 YAML 格式。它定义了网站的各种属性、文档结构、主题、插件等。

2.1 基本信息

这些参数定义了网站的基本元数据。

• site_name:

  • 描述：您的网站名称，将显示在浏览器标题栏和网站顶部导航栏。
  • 示例：site_name: 滚揉机控制器文档

• site_url: (可选，但推荐设置)

  • 描述：您的网站最终部署的 URL。用于生成站点地图和 RSS feed。
  • 示例：site_url: https://docs.yourcompany.com/ (本地测试时可设为 http://localhost:8000/)

• site_description: (可选)

  • 描述：网站的简短描述，用于搜索引擎优化 (SEO)。
  • 示例：site_description: 滚揉机控制器产品使用说明和技术文档

• repo_url: (可选)

  • 描述：您的文档源代码仓库的 URL（如 GitHub, GitLab）。
  • 示例：repo_url: https://github.com/your-org/your-repo/

• repo_name: (可选)

  • 描述：仓库名称，通常显示在网站右上角。如果未设置，则从 repo_url 自动推断。
  • 示例：repo_name: GitHub

• edit_uri: (可选)

  • 描述：允许用户直接跳转到 Git 仓库的编辑页面。与 repo_url 结合使用。
  • 示例：edit_uri: edit/main/docs/ (假设您的主分支是 main，文档在 docs 目录)

2.2 主题配置 (theme)

此部分配置网站的外观和行为。

• name:

  • 描述：指定使用的主题名称。material 是一个非常流行且功能强大的第三方主题。
  • 示例：name: material

• language:

  • 描述：设置网站的语言，影响日期、搜索提示等。
  • 示例：language: zh (中文)

• features: (Material 主题特有)

  • 描述：启用 Material for MkDocs 主题的各种高级功能。
  • 常用示例：

    features:
      - navigation.tabs       # 启用顶部导航选项卡
      - navigation.indexes    # 允许子目录有索引页 (如 directory/index.md)
      - toc.integrate         # 将页面内目录集成到侧边栏导航中
      - search.suggest        # 搜索建议
      - search.highlight      # 搜索结果高亮
      - content.tabs          # 在 Markdown 中使用选项卡 (如 ```tabs)
      - content.code.copy     # 为代码块添加复制按钮
      - content.action.edit   # 在页面底部显示编辑链接 (需配置 edit_uri)
    

• palette: (Material 主题特有)

  • 描述：配置网站的颜色主题，包括主色和强调色。
  • 示例：

    palette:
      - scheme: default       # 默认配色方案
        primary: indigo       # 主色
        accent: light blue    # 强调色
        toggle:
          icon: material/toggle-switch-off-outline # 关闭图标
          name: Switch to dark mode
      - scheme: slate         # 深色配色方案
        primary: indigo
        accent: light blue
        toggle:
          icon: material/toggle-switch-outline # 打开图标
          name: Switch to light mode
    

• custom_dir: (高级，可选)

  • 描述：指定一个包含自定义主题文件（如 CSS, JS, HTML 模板）的目录，用于覆盖或扩展默认主题。
  • 示例：custom_dir: overrides

2.3 文档目录 (docs_dir)

• 描述：指定您的 Markdown 源文件所在的目录。此路径是相对于 mkdocs.yml 文件的。
• 重要：这个目录应该只包含您的 Markdown 文件和图片等相关资源。
• 示例：
  • 如果 mkdocs.yml 在项目根目录，文档在 docs/ 子目录：docs_dir: 'docs'
  • 在您的案例中，mkdocs.yml 在 G:\AD元件库\XR-GRJ-001\，文档在 G:\AD元件库\XR-GRJ-001\Markdown\：docs_dir: 'Markdown'

2.4 导航 (nav)

• 描述：定义网站的导航结构和页面顺序。这是构建网站菜单的关键。
• 格式：使用 YAML 列表和字典的组合来定义菜单项和子菜单。
• 示例：

  nav:
    - 首页: 'index.md'               # 单个页面
    - 产品指南:                     # 父级菜单
      - 安装: 'product/install.md'  # 子页面
      - 使用: 'product/usage.md'
    - API 参考: 'api_reference.md'   # 另一个顶级页面
    - 关于我们:                     # 可以嵌套多层
      - 公司简介: 'about/company.md'
      - 联系方式: 'about/contact.md'
  

  注意： 文件路径是相对于 docs_dir 的。

2.5 额外配置 (extra)

• 描述：一个通用的字典，用于存储您希望在主题模板中访问的自定义变量。
• 示例：

  extra:
    author: 您的公司名称
    version: 1.0.0
    copyright: 'Copyright ? 2023 - 2024'
  

2.6 插件 (plugins)

• 描述：用于扩展 MkDocs 功能的列表。通常会包含 search 插件。
• 常用示例：

  plugins:
    - search           # 默认搜索插件
    - techdocs-core    # 如果使用Backstage TechDocs
    - mkdocstrings     # 从代码中生成文档
  

2.7 Markdown 扩展 (markdown_extensions)

• 描述：启用额外的 Markdown 语法功能，这些功能通常由 Python Markdown 库提供。
• 常用示例：

  markdown_extensions:
    - admonition        # 支持警告框 (Note, Warning, Tip 等)
    - pymdownx.details  # 可折叠的细节框
    - pymdownx.superfences # 更好的代码块支持
    - pymdownx.critic   # 审阅标记
    - attr_list         # 为元素添加属性 (如 {.className #id})
    - def_list          # 定义列表
    - footnotes         # 脚注
    - pymdownx.highlight # 代码高亮
    - pymdownx.inlinehilite # 行内代码高亮
    - pymdownx.keys     # 按键标记
    - pymdownx.mark     # 文本标记
    - pymdownx.tilde    # 下划线和删除线
    - pymdownx.caret    # 上标
    - pymdownx.tasklist: # 任务列表
        custom_checkbox: true
    - pymdownx.emoji:    # Emoji 支持
        emoji_index: !!python/name:material.extensions.emoji.twemoji
        emoji_generator: !!python/name:material.extensions.emoji.to_svg
  

2.8 额外 CSS/JS (extra_css, extra_javascript)

• 描述：用于引入自定义的 CSS 样式表和 JavaScript 文件。这些文件应放置在 docs_dir 目录（例如 Markdown 目录）下，并使用相对于 docs_dir 的路径引用。
• 示例：

  extra_css:
    - stylesheets/extra.css
  
  extra_javascript:
    - javascripts/extra.js
  

  (假设您在 Markdown 目录下创建了 stylesheets 和 javascripts 文件夹)

---

希望这份详细的教程能帮助您更好地理解和使用 MkDocs！