【未完待续】MkDocs 部署安装教程

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

注：

1. 以 . 开头的文件将被 MkDocs 所忽略。
2. 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

【未完待续】