开始使用 MkDocs
一个入门教程！
安装
要安装 MkDocs，请从命令行运行以下命令：
pip install mkdocs更多详情，请参阅安装指南。
创建新项目
开始非常简单。要创建一个新项目，请从命令行运行以下命令：
mkdocs new my-project
cd my-project花点时间查看一下为你创建的初始项目。
有一个名为 mkdocs.yml 的单一配置文件，以及一个名为 docs 的文件夹，该文件夹将包含你的文档源文件（docs 是 docs_dir 配置设置的默认值）。现在，docs 文件夹只包含一个名为 index.md 的文档页面。
MkDocs 自带一个内置的开发服务器，让你在编写文档时可以预览。确保你在 mkdocs.yml 配置文件所在的目录中，然后通过运行 mkdocs serve 命令启动服务器：
$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
INFO - Documentation built in 0.22 seconds
INFO - [15:50:43] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO - [15:50:43] Serving on http://127.0.0.1:8000/在你的浏览器中打开 http://127.0.0.1:8000/，你会看到默认的主页：
开发服务器还支持自动重新加载，并且会在配置文件、文档目录或主题目录中的任何内容发生变化时重新构建你的文档。
在你选择的文本编辑器中打开 docs/index.md 文档，将初始标题更改为 MkLorum，并保存更改。你的浏览器将自动重新加载，你应该会立即看到更新的文档。
现在尝试编辑配置文件：mkdocs.yml。将 site_name 设置更改为 MkLorum 并保存文件。
site_name: MkLorum你的浏览器应立即重新加载，你会看到新的站点名称生效。
注意：
site_name 配置选项是配置文件中唯一必需的选项。
添加页面
现在向你的文档添加第二个页面：
curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md由于我们的文档站点将包含一些导航标题，你可能希望编辑配置文件并添加一些关于导航标题中每个页面的顺序、标题和嵌套的信息，方法是添加一个 nav 设置：
site_name: MkLorum
nav:
- Home: index.md
- About: about.md保存更改后，你现在会在左侧看到一个带有 Home 和 About 项目的导航栏，以及右侧的 Search、Previous 和 Next 项目。
尝试菜单项并在页面之间来回导航。然后点击 Search。一个搜索对话框将出现，允许你在任何页面上搜索任何文本。注意，搜索结果包括站点上搜索词的每个出现位置，并直接链接到页面中搜索词出现的部分。你无需任何努力或配置即可获得所有这些功能！
为文档设置主题
现在更改配置文件以改变文档的显示方式，方法是更改主题。编辑 mkdocs.yml 文件并添加一个 theme 设置：
site_name: MkLorum
nav:
- Home: index.md
- About: about.md
theme: readthedocs保存更改后，你会看到正在使用 ReadTheDocs 主题。
更改 Favicon 图标
默认情况下，MkDocs 使用 MkDocs favicon 图标。要使用不同的图标，请在 docs 目录中创建一个 img 子目录，并将你的自定义 favicon.ico 文件复制到该目录。MkDocs 将自动检测并使用该文件作为你的 favicon 图标。
构建站点
看起来不错。你已经准备好部署 MkLorum 文档的第一版了。首先构建文档：
mkdocs build这将创建一个名为 site 的新目录。查看一下目录内容：
$ ls site
about fonts index.html license search.html
css img js mkdocs sitemap.xml注意，你的源文档已输出为两个名为 index.html 和 about/index.html 的 HTML 文件。你还有各种其他媒体作为文档主题的一部分被复制到 site 目录中。你甚至有一个 sitemap.xml 文件和 mkdocs/search_index.json。
如果你使用 git 等源代码控制，你可能不希望将文档构建检查到仓库中。在你的 .gitignore 文件中添加一行包含 site/。
echo "site/" >> .gitignore如果你使用的是其他源代码控制工具，你需要查阅其文档以了解如何忽略特定目录。
其他命令和选项
还有各种其他命令和选项可用。要获取完整的命令列表，请使用 --help 标志：
mkdocs --help要查看某个命令可用的选项列表，请在该命令后使用 --help 标志。例如，要获取 build 命令的所有可用选项，请运行以下命令：
mkdocs build --help部署
你刚刚构建的文档站点仅使用静态文件，因此你可以从几乎任何地方托管它。只需将整个 site 目录的内容上传到你托管网站的地方，就完成了。有关许多常见主机的具体说明，请参阅部署你的文档页面。
获取帮助
有关 MkDocs 所有功能的更完整文档，请参阅用户指南。