@[toc]
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官方文档,了解更多详细信息。