MkDocs 官方最新版 v1.1.2

软件介绍

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

MkDocs软件功能

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

特征

从Markdown文件构建静态HTML文件。

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

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

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

MkDocs软件特色

1、在任何地方托管

MkDocs构建完全静态的HTML网站，您可以将其托管在GitHub页面，Amazon S3或您选择的任何其他位置。

2、伟大的主题可用

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

3、工作时预览您的网站

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

4、易于定制

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

MkDocs教程

入门

入门非常容易。

mkdocs new 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 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

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

保存所做的更改，您现在将看到一个导航栏，其中带有Home和的About 项目位于左侧Search，而Previous，，以及Next项目位于右侧。

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

主题化我们的文档

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

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

更改图标图标

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

建立网站

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

mkdocs build

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

请注意，您的源文档已作为两个名为index.html和的HTML文件输出 about/index.html。您还可以将其他各种媒体site作为文档主题的一部分复制到目录中。您甚至还有一个sap.xml文件和mkdocs/search_index.json。

如果您正在使用源代码控制，例如，git您可能不想文档库在存储库中的构建。site/在.gitignore文件中添加一行 。

echo "site/" >> .gitignore

如果您使用的是其他源代码控制工具，则需要查看其有关如何忽略特定目录的文档。

一段时间后，文件可能会从文档中删除，但仍将保留在site目录中。要删除这些过时的文件，只需mkdocs 使用该--clean开关即可运行。

mkdocs build --clean

其他命令和选项

还有其他各种命令和选项。有关命令的完整列表，请使用--标志：

mkdocs --

要查看给定命令可用的选项列表，请将该--标志与该命令一起使用。例如，要获取该build命令可用的所有选项的列表，请 运行以下命令：

mkdocs build --