MkDocs是一个用于生成静态文档网站的Python第三方库。 它使用Markdown语言来编译文档，并提供许多主题和插件来定制生成的文档网站。 在本教程中，我们将学习如何使用 MkDocs 创建和自定义我们自己的文档网站。
安装 MkDocs
首先，我们需要安装 MkDocs。 MkDocs 可以使用 pip 工具安装。 在终端中输入以下命令：
pip install mkdocs
创建 MkDocs 项目
接下来，我们需要创建一个 MkDocs 项目。 您可以在命令行上使用 MkDocs 命令来创建新项目。 在终端中输入以下命令：
mkdocs new my-project
该命令将在当前目录中创建一个名为“my-project”的新目录，并在其中创建一个名为“docs”的子目录，其中将包含一个名为“index.md”的 Markdown 文件。
编写 Markdown 文件
现在，可以在“docs”目录中创建和编辑 Markdown 文件。 您可以创建任意数量的 Markdown 文件并使用 Markdown 语法来编译文档。 例如，您可以创建一个名为“getting-started.md”的文件，其中包含以下内容：
# Getting Started
To get started with MkDocs, you need to install it and create a new project.
## Installation
To install MkDocs, run the following command:
pip 安装 mkdocs
## Creating a new project
To create a new project, run the following command:
mkdocs 新的我的项目
This will create a new directory called `my-project` with a `docs` subdirectory containing an `index.md` file.
## Building the site
To build the site, run the following command:
mkdocs 构建
This will generate a static site in the `site` directory.
配置 MkDocs
MkDocs 提供了一个名为“mkdocs.yml”的配置文件html头文件，用于自定义生成的文档网站。 主题、插件、导航栏等可以在此文件中定义。
例如，“mkdocs.yml”中的默认配置可以替换为以下内容：
site_name: My Project
theme:
name: readthedocs
nav:
- Home: index.md
- Getting Started: getting-started.md
在本例中，我们将站点名称设置为“我的项目”，使用“readthedocs”主题html头文件，并定义一个包含“主页”和“入门”两个页面的导航栏。
构建并预览网站
现在可以使用 MkDocs 命令构建和预览生成的文档网站。 在终端中输入以下命令：
mkdocs build
mkdocs serve
第一个命令“mkdocs build”会将 Markdown 文件编译为静态 HTML 文件，并将它们放在名为“site”的目录中。
第二个命令“mkdocsserve”将启动本地Web服务器，并且可以在浏览器中访问生成的网站。 在浏览器中输入以下 URL：:8000/ 查看网站。
部署网站
最后，生成的文档网站可以部署到远程服务器或静态文件托管服务。 例如，您可以使用 GitHub Pages 来托管您的网站。
首先，在MkDocs项目的根目录下创建一个名为“docs”的分支，并将MkDocs生成的静态网站文件放置在分支中的“site”目录中。 然后，将该分支推送到 GitHub 存储库。
接下来，在 GitHub 存储库的设置页面中启用 GitHub Pages，并将“Source”设置为“docs”分支。 这将使 GitHub Pages 手动构建和托管 MkDocs 生成的文档网站。
现在，您可以输入 GitHub Pages URL（通常：.github.io/
/) 查看托管站点。
总结
MkDocs是一个功能强大的工具，可以帮助我们轻松创建和定制自己的文档网站。 本教程介绍如何安装和配置 MkDocs、编写 Markdown 文件、构建和预览网站以及将网站部署到 GitHub Pages。 希望本教程可以帮助您开始使用 MkDocs 创建您自己的文档站点。
