Skip to content

首页

MkDocs 是一个快速、简单且华丽的静态站点生成器，适用于构建项目文档。文档源文件是用 Markdown 编写的，并使用单个 YAML 配置文件进行配置。

特征：

  • 很棒的主题可供选择：MkDocs有一堆好看的主题可供使用。在内置主题之间进行选择： mkdocs和 readthedocs，选择第三方主题之一（在MkDocs 主题wiki 页面以及MkDocs Catalog上），或者构建您自己的.
  • 易于定制：通过自定义主题和/或安装一些插件 ，让您的项目文档看起来就像您想要的那样 。使用Markdown 扩展修改 Markdown 的行为。有许多配置选项可用。
  • 在工作时预览您的网站：内置的开发服务器允许您在编写文档时预览文档。每当您保存更改时，它甚至会自动重新加载并刷新您的浏览器。
  • 随处托管：MkDocs 构建完全静态的 HTML 站点，您可以将其托管在 GitHub Pages、Amazon S3 或您选择的任何其他地方。

安装 MkDocs

运行环境

Mkdocs是用Python开发的工具，可以使用pip命令来安装。

$ python --version
Python 3.12.2
$ pip --version
pip 24.0

安装MkDocs

$ pip install mkdocs
$ mkdocs --version
mkdocs, version 1.6.0
# 安装mkdocs-material主题
$ pip install mkdocs-material

快速开始

$ mkdocs new my-project
INFO    -  Creating project directory: my-project
INFO    -  Writing config file: my-project\mkdocs.yml
INFO    -  Writing initial docs: my-project\docs\index.md

这样就会在本地建立一个my-project文件夹　其中包括了一个mkdocs.yml和一个docs文件夹

  • mkdocs.yml：这个文件是一个配置文件主要配置你的站点名字，板块等
  • docs：是存放你要写的Markdown文档的地方

在本地查看搭建的文档效果

$ cd my-project
$ mkdocs serve
Running at: http://127.0.0.1:8000/

然后访问http://127.0.0.1:8000就可以看到生成文档的效果了

发布网站

$ mkdocs build
INFO    -  Building documentation to directory: my-project\site

这样就发布成功了，就会在my-project文件夹下生成一个site文件夹，里面是生成的静态网站文件，将site文件夹中的内容上传到服务器即可。