mkdocs_使用MkDocs构建产品文档

mkdocs

There's a popular maxim that "a product is as good as its documentation". This holds true as much for software as it does for physical products.

有一个流行的格言，即“产品与其文档一样好”。 对于软件和对物理产品而言，这都适用。

As a small, indie developer who doesn't specialize in front-end design, I often hire a freelancer to build my product website—which, of course, usually includes a documentation section.

作为一个不专门从事前端设计的小型独立开发人员，我经常聘请自由职业者来构建我的产品网站-当然，该网站通常包括文档部分。

A documentation section can take quite a bit of time and money to build, even for a simple product, so it would be nice not to have to reinvent the wheel for every site. Fortunately, there is a way.

即使对于一个简单的产品，文档部分的构建也可能会花费大量的时间和金钱，因此不必为每个站点重新发明轮子会很好。 幸运的是，有一种方法。

介绍MkDocs (Introducing MkDocs)

MkDocs is a free, static site generator geared towards building project documentation. It can be used to generate a stand-alone site, or just a documentation section of a larger site.

MkDocs是一个免费的静态站点生成器，专门用于构建项目文档。 它可以用于生成独立站点，或者仅用于生成较大站点的文档部分。

Because MkDocs produces static files, your documentation is light-weight and easy to host—using free services such as GitHub Pages and Read The Docs—or of course on your own server.

由于MkDocs生成静态文件，因此您的文档重量轻且易于托管(使用GitHub Pages和Read The Docs等免费服务)，当然也可以在您自己的服务器上。

In this article, I'll introduce MkDocs, showing you how to install it, build documentation with it and finally host the generated documentation on a web server.

在本文中，我将介绍MkDocs，向您展示如何安装它，使用它构建文档以及最终将生成的文档托管在Web服务器上。

To get a sense of the sort of documentation MkDocs produces, have a look at my ProfilePress WordPress plugin documentation, which is built with MkDocs using the Read the Docs theme.

要了解MkDocs生成的文档类型，请查看我的ProfilePress WordPress插件文档 ，该文档是使用MkDocs使用Read the Docs主题构建的。

MkDocs is written in Python. The documentation source files are written in Markdown, and configured with a single YAML configuration file.

MkDocs用Python编写。 文档源文件使用Markdown编写，并使用单个YAML配置文件进行配置。

To build documentation with MkDocs, you need to have it installed locally in your computer. So let's next look at how to install it.

要使用MkDocs构建文档，您需要将其本地安装在计算机中。 因此，让我们接下来看看如何安装它。

安装Python和MkDocs (Installing Python and MkDocs)

Static site generators like Jekyll (used mainly for blogging, and built on Ruby) and MkDocs do require some command-line chops, so be warned. However, to those not used to working with the command line, I encourage you to read on and give it a try, as it's not as bad as it looks!

静态站点生成器，例如Jekyll(主要用于撰写博客，并基于Ruby构建)和MkDocs确实需要一些命令行操作，因此请注意。 但是，对于不习惯使用命令行的用户，我建议您继续阅读并尝试一下，因为它并不像看起来那样糟糕！

安装Python和pip (Installing Python and pip)

To install MkDocs, you need to have Python and