LET ME HELP YOU

Welcome to MkDocs

For full documentation visit mkdocs.org官网.

MkDocs 使用说明

介绍

MkDocs 是一个静态网站生成器，专为构建项目文档而设计。它使用 Markdown 文件和一个 YAML 配置文件，生成一个漂亮的文档网站。其主要特点包括：

使用 Markdown 编写文档
支持多种主题
实时预览
部署到 GitHub Pages

安装

首先，你需要确保已经安装了 Python。然后，通过以下命令安装 MkDocs：

pip install mkdocs

你也可以选择安装一个主题，例如 mkdocs-material：

pip install mkdocs-material

创建项目

使用以下命令创建一个新的 MkDocs 项目：

mkdocs new my-project
cd my-project

这将生成一个包含基本项目结构的目录 my-project。

项目结构

典型的 MkDocs 项目结构如下：

my-project/
    mkdocs.yml    # 配置文件
    docs/
        index.md  # 主页面内容

配置文件 `mkdocs.yml`

mkdocs.yml 是 MkDocs 的配置文件，包含站点的基本设置。以下是一个简单的示例：

site_name: 我的文档

nav:
    - 首页: index.md
    - 介绍: about.md

theme: material

配置选项

site_name: 站点的名称，将显示在网站的导航栏中。
nav: 定义导航栏的内容和结构。可以是文件路径的列表，也可以是嵌套的目录结构。
theme: 定义使用的主题。可以是内置主题，也可以是第三方主题。

添加内容

你可以在 docs 目录中添加 Markdown 文件。例如，创建一个 about.md 文件：

# 介绍

这是一个关于项目的介绍。

还可以创建子目录来组织内容，例如：

docs/
    index.md
    about.md
    user-guide/
        installation.md
        usage.md

在 mkdocs.yml 中更新导航结构：

nav:
    - 首页: index.md
    - 介绍: about.md
    - 用户指南:
        - 安装: user-guide/installation.md
        - 使用: user-guide/usage.md

运行开发服务器

在项目目录中运行以下命令以启动内置的开发服务器：

mkdocs serve

然后在浏览器中打开 http://127.0.0.1:8000/ 查看效果。开发服务器会实时更新你所做的任何更改。

mkdocs serve 命令可以自定义 IP 和端口。你可以使用 -a 或 --dev-addr 选项来指定 IP 地址和端口。默认情况下，mkdocs serve 会在 127.0.0.1:8000 上启动服务器。以下是一些例子：

示例用法

指定端口： bash mkdocs serve -a 127.0.0.1:9000 这将会在本地 IP 127.0.0.1 上的端口 9000 启动开发服务器。
指定 IP 和端口： bash mkdocs serve -a 192.168.1.100:8080 这将在局域网内的 IP 192.168.1.100 上的端口 8080 启动开发服务器。这样你可以在同一个网络内的其他设备上访问文档站点。
监听所有网络接口： bash mkdocs serve -a 0.0.0.0:8000 这将会监听所有网络接口上的端口 8000，使得文档站点可以通过任意网络接口访问。

常见问题

防火墙或网络配置问题： 如果你在指定 IP 和端口后无法访问开发服务器，请检查你的防火墙设置和网络配置，确保所选的端口和 IP 可用并未被其他应用占用。
权限问题： 在一些系统上，绑定到特定的端口（例如，低于 1024 的端口）可能需要管理员权限。如果遇到权限问题，可以尝试使用高于 1024 的端口，或者以管理员身份运行命令。

通过这些设置，你可以灵活地配置 MkDocs 开发服务器，以满足不同的开发和测试需求。

构建站点

当你准备好发布文档时，运行以下命令以生成静态文件：

mkdocs build

这将在 site 目录中生成静态文件，可以部署到任何支持静态文件的网站服务器上。

自定义主题

你可以通过修改 mkdocs.yml 文件中的 theme 部分来自定义主题。例如，使用 mkdocs-material 主题：

theme:
    name: material

自定义 CSS 和 JavaScript

你还可以通过添加自定义 CSS 或 JavaScript 文件来自定义外观。在 docs 目录中创建 stylesheets 和 javascripts 文件夹，并添加相应的文件：

docs/
    stylesheets/
        extra.css
    javascripts/
        extra.js

在 mkdocs.yml 中引用这些文件：

extra_css:
    - stylesheets/extra.css

extra_javascript:
    - javascripts/extra.js

配置插件

MkDocs 支持使用插件来扩展其功能。插件可以提供额外的功能，如搜索、版本控制、多语言支持等。例如，可以使用 search 插件来添加搜索功能：

plugins:
    - search

下面是如何使用插件的详细说明，包括一些常见插件的示例。

安装插件

要使用 MkDocs 插件，你需要通过 pip 安装相应的插件包。例如，安装搜索插件：

pip install mkdocs-plugin-search

配置插件

安装插件后，你需要在 mkdocs.yml 文件中进行配置。例如，启用搜索插件：

site_name: 我的文档

theme:
    name: material

plugins:
    - search

常用插件示例

1. MkDocs Search

MkDocs Search 插件为网站添加了搜索功能。此插件通常默认包含在 MkDocs 安装包中，但如果你使用自定义主题或需要高级搜索功能，可以显式地配置它。

安装：

pip install mkdocs-plugin-search

配置：

plugins:
    - search

2. MkDocs Redirects

MkDocs Redirects 插件允许你在文件路径更改时设置重定向，以避免链接断开。

安装：

pip install mkdocs-redirects

配置：

plugins:
    - redirects

定义重定向规则：

redirects:
    old-path.md: new-path.md

3. MkDocs GitHub Pages

MkDocs GitHub Pages 插件可以帮助你将 MkDocs 网站自动部署到 GitHub Pages。

安装：

pip install mkdocs-gh-pages

配置：

plugins:
    - gh-deploy

4. MkDocs Minify

MkDocs Minify 插件可以在构建过程中压缩 HTML 文件，以减少文件大小和加载时间。

安装：

pip install mkdocs-minify-plugin

配置：

plugins:
    - minify

5. MkDocs Versioning

MkDocs Versioning 插件允许你为文档创建多个版本，并在站点中进行切换。

安装：

pip install mike

配置：

plugins:
    - mike

自定义插件

如果现有的插件不能满足你的需求，你还可以编写自己的 MkDocs 插件。下面是一个简单的示例插件，它会在每个页面的顶部添加一个自定义的注释。

在你的项目中创建一个 plugins 目录，并在其中创建一个 my_plugin.py 文件：

my-project/ mkdocs.yml docs/ plugins/ my_plugin.py

编写插件代码

在 my_plugin.py 文件中编写插件代码：

```python from mkdocs.plugins import BasePlugin from mkdocs.config import config_options

class MyPlugin(BasePlugin): config_scheme = ( ('note', config_options.Type(str, default='这是一个自定义注释')), )

   def on_page_markdown(self, markdown, **kwargs):
       note = self.config['note']
       return f'{note}\n\n{markdown}'

```

在 mkdocs.yml 中启用插件

```yaml site_name: 我的文档

theme: name: material

plugins: - search - my_plugin: note: "警告：这只是一个示例！" ```

将插件路径添加到 PYTHONPATH

启动开发服务器前，需要将插件路径添加到 PYTHONPATH：

bash export PYTHONPATH="${PYTHONPATH}:/path/to/my-project/plugins" mkdocs serve

插件钩子

MkDocs 插件可以使用多种钩子来修改站点的各个部分：

on_config: 修改配置
on_pre_build: 构建前的操作
on_page_markdown: 修改页面的 Markdown 内容
on_page_content: 修改页面的 HTML 内容
on_post_build: 构建后的操作

部署到 GitHub Pages

MkDocs 提供了一个简单的命令可以将站点部署到 GitHub Pages。首先，确保你已经初始化了 git 仓库并添加了远程仓库。然后运行：

mkdocs gh-deploy

这将构建站点并将其推送到 gh-pages 分支。

手动部署

如果你不使用 GitHub Pages，还可以手动部署生成的静态文件。将 site 目录中的内容上传到你选择的服务器或托管服务上即可。

高级用法

多语言支持

MkDocs 本身不直接支持多语言，但可以通过插件或手动配置实现。例如，可以使用 mkdocs-multirepo-plugin：

plugins:
    - multirepo:
        repo:
            - name: en
              url: git@github.com:user/repo-en.git
            - name: zh
              url: git@github.com:user/repo-zh.git

自动生成文档

可以使用工具如 pydoc 或 sphinx 来自动生成代码文档，然后集成到 MkDocs 项目中。例如，使用 sphinx 生成 HTML 文档并复制到 docs 目录中。

集成 CI/CD

可以使用 CI/CD 工具如 GitHub Actions 或 GitLab CI 自动化文档构建和部署。以下是一个 GitHub Actions 配置示例：

name: Deploy MkDocs

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v2

    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.x'

    - name: Install dependencies
      run: pip install mkdocs mkdocs-material

    - name: Build MkDocs site
      run: mkdocs build

    - name: Deploy to GitHub Pages
      run: mkdocs gh-deploy --force

Welcome to MkDocs

MkDocs 使用说明

介绍

安装

创建项目

项目结构

配置文件 mkdocs.yml

配置选项

添加内容

运行开发服务器

示例用法

常见问题

构建站点

自定义主题

自定义 CSS 和 JavaScript

配置插件

安装插件

配置插件

常用插件示例

1. MkDocs Search

2. MkDocs Redirects

3. MkDocs GitHub Pages

4. MkDocs Minify

5. MkDocs Versioning

自定义插件

插件钩子

部署到 GitHub Pages

手动部署

高级用法

多语言支持

自动生成文档

集成 CI/CD

更多信息

配置文件 `mkdocs.yml`