MkDocs 简介
- MkDocs 是一个基于 Python 的 Markdown 的静态网站生成工具,常用于快速搭建项目文档网站。
- 它界面简洁大方,配置简单,生成速度快,特别适合技术手册、内部知识库等场景,并可部署到 Github Pages,因此深受开发者喜爱。
- MkDocs 使用 Python-Markdown 库将 Markdown 文档渲染为 HTML。
- MkDocs 中文官网:mkdocs.org.cn
- 接下来,笔者将在 Ubuntu 24.04 LTS 上搭建 MkDocs。
本博客已假定读者了解 Markdown,并会使用 Python 包管理器 pip、虚拟环境管理器 venv ,Linux 基础命令,以及 yml 格式配置文件的编写。若不了解,请自行 Google,本博客不会讲解其他内容的原理。
MkDocs 部署
基础环境安装
MkDocs 建议 Python>=3.9,使用python3 --version
查看 Python 版本。
创建项目文件夹
创建 MkDocs 项目根目录并进入:
mkdir mkdocs && cd mkdocs
创建虚拟环境(推荐)
这一步是极其推荐的,确保不污染全局 Python 环境。
python3 -m venv venv
source venv/bin/activate
每次运行时都需使用 source venv/bin/activate
加载此虚拟环境。
安装 MkDocs
MkDocs 本体及其大多数扩展都是以 Python 库形式发布的,使用 pip 安装即可:
pip install mkdocs
初始化文档项目
在根目录下初始化 MkDocs 项目:
mkdocs new .
这时会生成一个 mkdocs.yml
配置文件 和 docs/
文件夹,MkDocs 的目录结构如下:
mkdocs/
├── mkdocs.yml # 配置文件
└── docs/ # 默认文档目录└── index.md # 首页文档
其中 docs
目录为默认文档目录,其可通过配置文件的 docs_dir
选项调整。
初步运行
MkDocs 内置了一个支持热重载的开发服务器,在项目根目录下使用以下命令启动服务器:
mkdocs serve
此时服务器开始尝试启动,并在控制台输出启动日志,若出错则会显示错误原因。请注意日志中 Serving on:
一行,其指定了服务器 IP 及监听的端口号,通常为 http://127.0.0.1:8000
,访问此 URL 即可查看网站。
至此,已成功在本地运行起了一个最小可用版的MkDocs。
配置文件:mkdocs.yml (核心步骤)
MkDocs 所有配置均通过此文件调整。
设置站点标题
在 mkdocs.yml
中编写:
site_name: Blogs
配置文件中的 site_name
是必选项。
设置站点图标
在 docs
目录下创建子目录 img
,并将 favicon.ico
放置在 img
目录下。
添加页面
- MkDocs 默认将
docs
下所有的.md
文件加入到网站页面中,因此无需手动添加。 - 网站首页即为
index.md
,URL 为根目录/
,其他文件的 URL 即为该文件的相对路径位置。
注意:不推荐使用中文命名的文件,这会导致 URL 中出现中文,这是不推荐的做法,在SEO中将使搜索引擎难以解析。
- 页面默认标题为
.md
文件中的首个一级标题。
设置导航栏菜单
方法是在 mkdocs.yml
中编写 nav
配置,网站菜单将按此配置定义的顺序排布。注意所用到的文件均为相对于 docs
的路径。
nav:- index.md- about.md
注:
- 以
.
开头的文件将被 MkDocs 所忽略。nav
配置仅决定菜单顺序,而不决定文件的 URL。URL 始终为该文件相对于docs
的路径。
页面默认标题为 .md
文件中的首个一级标题,也可手动指定页面标题,方法为标题: 文件
:
标题编写规范:一般地,页面应该有且仅有一个语义明确的一级标题,用来表示页面主题。其余标题作为主标题下的小节,应从二级标题开始。
nav:- 首页: index.md- 关于: about.md
也可设置多级菜单:
nav:- 首页: index.md # 一级菜单- 政策: # 二级菜单- 关于: about.md- 用户支持: # 三级菜单- 手册: guide.md- 联系: contact.md
主题
Mkdocs支持若干主题,其包含两个内置主题 mkdocs(默认主题) 和 readthedocs,也支持其他若干第三方主题。切换主题方法是在 mkdocs.yml
中添加 theme
配置,如:
theme: readthedocs
本文将使用第三方主题 material,它是排名第一的第三方主题,被大量广泛使用。在终端执行如下命令安装:
pip install mkdocs-material
添加至 mkdocs.yml
:
theme: material
【未完待续】