MkDocs

MkDocs简介

MkDocs提供静态网站生成功能，可以帮助用户通过该软件快速生成个人网站。该软件提供了许多主题内容。您可以自定义网站主题和HTML样式。大部分主题都可以自己配置。页面由Markdown编辑。现在所有的Markdown页面都包含在构造中，无论它们是否包含在导航配置中。导航现在可以包含到外部网站的链接，自动填充导航现在将索引页面放在顶部。换句话说，索引页将被列为目录的第一个子级，而所有其他文档将根据索引页后面的文件名按字母顺序排序。提供一个新的url模板过滤器可以巧妙地保证所有L都是相对于当前页面的！

MkDocs软件功能

MkDocs是一种面向建设项目文件的快速、简单、彻头彻尾的华丽网站生成器。文档源文件用Markdown编写，并用单个YAML配置文件进行配置。它的设计很容易使用，可以通过第三方主题、插件和Markdown扩展进行扩展。

特性

从标记文件构建一个静态的HTML文件。

使用插件和Markdown扩展来增强MkDocs。

使用内置主题、第三方主题或创建自己的主题。

将文档发布到可以提供静态文件的任何位置。

MkDocs软件特色

1.相信任何地方。

MkDocs建立一个完全静态的HTML网站，可以托管在GitHub页面、亚马逊S3或你选择的任何其他位置。

2.伟大的主题是可用的

MkDocs提供了许多美丽的话题。在内置主题:mkdocs和readthedocs之间进行选择，选择MkDocs主题Wiki页面上列出的第三方主题之一，或者构建自己的主题。

3.在工作中预览您的网站。

内置开发-允许您在编写文档时预览文档。每当您保存更改时，它甚至会自动重新加载和刷新浏览器。

4.易于定制

通过自定义主题和/或安装一些插件，使您的项目文档看起来像您想要的那样。

MkDocs教程

初级课程

开始很容易。

mkdocs新my-pject

cd my-pject

花点时间回顾一下为您创建的初始项目。

有一个名为mkdocs.yml的配置文件，一个名为docs的文件夹将包含您的文档源文件。现在，docs文件夹只包含一个名为index.md的文档页面

MkDocs自带内置开发功能，可以让您在处理文档时预览文档。确保您与mkdocs.yml配置文件在同一个目录中，并通过运行以下mkdocs serve命令启动它:

Http://127.0.0.1:8000/在浏览器中打开，您将看到默认主页显示:

开发还支持自动重新加载，只要配置文件、文档目录或主题目录中的任何内容发生变化，您的文档就会被重建。

Docs/index.md在您选择的文本编辑器中打开文档，将初始标题更改为MkLorum，并保存您的更改。您的浏览器将自动重新加载，您应该会立即看到更新的文档。

现在尝试编辑配置文件:mkdocs.yml将site_name设置更改为MkLorum并保存文件。

site_name: MkLorum

您的浏览器应该立即重新加载，您将看到新的网站名称生效。

添加页面

现在将第二页添加到您的文档中:

curl & # 8216https://jaspervdj.be/lorem-markdownum/markdown.txt’。docs/about.md

由于我们的文档站点将包含一些导航标题，您可能需要编辑配置文件，并通过添加导航设置在导航标题中添加一些关于每个页面的顺序、标题和嵌套的信息:

保存您的更改，您现在将看到一个导航栏，其中“关于”项目和“主页”位于左侧“搜索”，而“上一个”、“下一个”项目位于右侧。

尝试菜单项在页面之间来回导航。单击搜索。将出现一个搜索对话框，允许您搜索任何页面上的任何文本。请注意，搜索结果包括网站上出现的所有搜索词，并直接链接到搜索词出现的页面部分。你可以毫不费力地完成所有的工作！

我们文档的主题

现在更改配置文件，通过更改主题来更改文档的显示方式。编辑mkdocs.yml文件并添加主题设置:

保存您的更改，您将看到您正在使用ReadTheDocs主题。

更改图标图标

默认情况下，MkDocs使用MkDocs图标图标。要使用其他图标，请在中创建一个img子目录，docs_dir将自定义favicon.ico文件复制到该目录。MkDocs将自动检测该文件并将其用作您的收藏夹图标。默认情况下，MkDocs使用MkDocs图标。要使用其他图标，请创建一个img子目录，docs_dir在其中复制自定义的favicon.ico文件。MkDocs将自动检测该文件，并将其用作您最喜欢的图标。

建立网站

很高兴看到您已经准备好部署MkLorum文档的第一阶段。首先构建文档:

mkdocs构建

这将创建一个名为site的新目录。看看目录:

请注意，您的源文档将/index.html输出为两个名为index.html和的html文件。您也可以将其他媒体网站复制到目录中，作为文档主题的一部分。你甚至有一个sap.xml文件和mkdocs/search _ index.json。

如果您正在使用源代码管理，例如git，您可能不希望文档库构建在存储库中。站点/向添加一行。gitignore文件。

回声& # 8220；站点/& # 8221；& gt& gt。被增加

如果您正在使用其他源代码管理工具，您需要查看它们的文档，了解如何忽略特定的目录。

一段时间后，该文件可能会从文档中删除，但会保留在网站目录中。要删除这些过时的文件，就用这个& # 8211；清洁开关可以运行。

mkdocs构建& # 8211；干净的

其他命令和选项

还有各种其他命令和选项。有关命令的完整列表，请使用& # 8211；徽标:

mkdocs & # 8212

要查看给定命令的可用选项列表，请设置此& # 8211；此命令使用标志。例如，要获取build命令所有可用选项的列表，请运行以下命令:

mkdocs构建& # 8212；