DevOps: Mkdocs 静态站点生成器 简介及实践

1.简介

MkDocs是一个基于Python的静态站点生成器，它可以将Markdown格式的文档转换为漂亮的静态网站。MkDocs提供了一种简单而灵活的方式来创建文档，并支持多种主题和插件。

2. 演示

下面是一个简单的示例代码，演示如何使用MkDocs创建一个文档站点：

2.1 安装MkDocs

可以使用pip命令安装MkDocs：

pip install mkdocs

2.2 初始化项目

使用mkdocs new命令初始化MkDocs项目，该命令会生成一个包含配置文件和目录结构的项目： 在项目根目录，命令行中使用mkdocs new来初始化文档。

$ python3 -m mkdocs new .
INFO     -  Writing config file: ./mkdocs.yml
INFO     -  Writing initial docs: ./docs/index.md

执行后在项目中生成docs目录及mkdocs.yml配置文件

2.3 编写文档

在docs目录下修改index.md，并新建其他Markdown格式的文档，如下图：

2.4 配置mkdocs.yml#

在mkdocs.yml中配置站点名称、描述、作者、url、导航菜单等信息等。

• site_name：站点名称
• site_url：站点 URL 链接
• site_author：站点作者
• site_description：站点描述
• copyright：版权信息
• repo_url：站点仓库 URL
• nav: 站点导航
• theme: 站点主题
• markdown_extensions: Markdown扩展

参考配置如下：

site_name: Python-YApi
site_description: Python Client for YApi base on HTTP apis.
site_author: Han Zhichao
site_url: http://localhost:8000
copyright: Copyright @ 2023 Han Zhichao, All rights reserved.
repo_url: https://github.com/hanzhichao/python-yapi
theme: mkdocs  # 默认主题

nav:
  - 首页: index.md
  - 安装方法: install.md
  - 使用方法: usage.md
  - 模块列表:
      - 项目管理: modules/project.md
      - 接口管理: modules/interface.md
  - 作者说明: author.md

所有文件的引用都是相对与docs目录，支持菜单及引用子目录文件，如“模块列表”。

2.5 预览站点

使用mkdocs serve命令预览站点，例如：

$ python3 -m mkdocs serve

该命令会启动一个本地服务器，可以在浏览器中访问http://localhost:8000 来查看站点，如下图：

2.6生成站点

使用mkdocs build命令生成静态站点，例如：

$ python3 -m mkdocs build

该命令会生成静态站点文件，保存在site目录下。

2.7 使用其他主题

在mkdocs.yml配置文件中使用theme可以指定主题(默认主题为mkdocs)。

使用readthedocs主题 修改mkdocs.yml，添加主题配置

theme: readthedocs

theme: readthedocs 安装mkdocs-material

pip install mkdocs-material

修改mkdocs.yml配置

theme: material

MkDocs还提供了丰富的配置选项和插件，可以根据需要进行定制。你可以参考MkDocs官方文档，了解更多详细信息。