Skip to content

mk总结

时间: 2024.12.03

使用 mkdocs 作为个人 wiki 已经有了一年多时间了，最近进一步尝试了 nginx 部署，对这个小工具有了更多的认识。为了方便后续查阅，这里做一些总结。核心的我将其归纳为两套部署体系：一个是生产快速部署，另一个则是真实部署。前者是根据 mkdocs 官方文档的部署方式，后者则是根据 mkdocs 构建文件，然后采用 nginx 配置文件来部署。

快速开始

无论是哪种部署方式，都需要提前具有 mkdocs 的环境。mkdocs 是 Python 中的一个包，但同时运行时需要系统具有 node 环境，因此首先需要安装在机器上安装 node， 然后根据 mkdocs 配置 Python 环境。

  1. node 安装。

  2. Python 安装，考虑到稳定性，建议安装一个 Python3.7 的环境。

  3. mkdocs 安装。安装方式很简单，直接使用 pip 安装即可。

pip install mkdocs
mkdocs --version        # 查看版本
  1. 相关包安装
pip install mkdocs-material         # 主题
pip install pymdown-extensions      # 数学公式
pip install mkdocs-jupyter          # py代码插件
  1. 创建一个 mkdocs 项目
mkdocs new my-project
cd my-project
  1. 启动 mkdocs 服务器
mkdocs serve
  1. 在浏览器中打开 http://127.0.0.1:8000/ 即可查看效果。

快速部署

写到这里，其实已经可以满足日常的使用需求了。快速部署就是上面提到的 mkdocs serve，它会在本地启动一个 mkdocs 服务器，然后通过浏览器访问即可。如果需要给本机以外的机器访问，则可以通过 mkdocs serve -a 0.0.0.0:8000 来启动，也可以在配置文件中修改。

快速部署也是日常使用中 debug 的一种手段，用来快速定位问题等，是一种最顺手的部署方式。

真实部署

快速部署虽然方便，但是它并不适合真实部署，因为快速部署的 mkdocs 服务器是单进程的，如果访问量过大，服务器就会挂掉。因此，真实部署需要使用多进程的 mkdocs 服务器，同时需要配合 nginx 来进行反向代理。详细的内容可以结合笔记（”记录一次nginx配置“）来学习。

相对于 nginx 的部署，需要提前完成对 mkdocs 网站的构建，构建方式如下：

mkdocs build

构建完成后，会在 mkdocs 项目目录下生成一个 mkdocs_site 文件夹，这个文件夹就是构建后的静态网站，可以直接使用 nginx 进行部署。

总结

mkdocs 是一个轻量级的静态网站生成器，它使用 markdown 文件作为内容，然后通过 mkdocs 构建后生成静态网站，然后通过 nginx 进行部署。mkdocs 的部署方式有两种，一种是快速部署，另一种是真实部署。快速部署适合日常使用，真实部署适合产品发布。