用Python写静态博客

MkDocs

使用Markdown的项目文档。

概观

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

主持任何地方

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

很棒的主题

MkDocs有一堆很好看的主题。在内置主题：mkdocs和readthedocs之间进行选择，在MkDocs wiki中选择第三方主题之一，或者构建自己的主题。

在您工作时预览您的网站

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

易于定制

通过自定义主题，让您的项目文档以您希望的方式查找。

（假设大家已经安装Python）

安装MkDocs

mkdocs使用pip 安装包：

pip install mkdocs

您现在应该mkdocs在系统上安装该命令。运行mkdocs --version以检查一切正常。

$ mkdocs --version
mkdocs, version 0.15.3

入门

入门非常简单。

mkdocs new my-projectcd my-project

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

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

MkDocs附带一个内置的开发服务器，可以让您在处理文档时预览文档。确保您与mkdocs.yml 配置文件位于同一目录中，然后通过运行以下mkdocs serve 命令启动服务器：

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes

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

dev-server还支持自动重新加载，并且只要配置文件，文档目录或主题目录中的任何内容发生更改，都将重建文档。

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

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

site_name: MkLorum

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

添加页面

现在在文档中添加第二页：

curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

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

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图标。要使用其他图标，请img在您的子目录中创建一个子目录，docs_dir然后将自定义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和的HTML文件 about/index.html。您还有各种其他媒体已site作为文档主题的一部分复制到目录中。你甚至有一个sitemap.xml文件和mkdocs/search_index.json。

如果您正在使用源代码控制，例如git您可能不希望将文档构建检查到存储库中。添加包含 site/在您的.gitignore文件中的行。

echo "site/" >> .gitignore

如果您正在使用其他源代码控制工具，则需要检查其文档，了解如何忽略特定目录。

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

mkdocs build --clean

其他命令和选项

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

mkdocs --help

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

mkdocs build --help

部署

您刚刚构建的文档站点仅使用静态文件，因此您几乎可以在任何地方托管它。GitHub项目页面和Amazon S3可能是很好的托管选项，具体取决于您的需求。将整个site目录的内容上传到您托管网站的任何地方，然后您就完成了。有关许多常见主机的具体说明，请参阅部署您的文档页面。

获得帮助

要获得有关MkDocs的帮助，请使用讨论组，GitHub问题或#mkdocsfreenode上的MkDocs IRC频道。

有兴趣的朋友可以阅读原文跳转到MkDocs网站浏览