使用MKDOC构建产品文档

>有一个受欢迎的格言，即“产品与文档一样好”。对于软件和物理产品，这与软件一样多。

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

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

钥匙要点

MKDOCS是一个免费的静态站点生成器，非常适合构建项目文档；它轻巧，易于托管，可用于独立站点或较大站点的文档部分。 必须在计算机上安装MKDOC，Python和Pip（Python软件包管理器）； MKDOCS在您的计算机上本地安装，使您可以离线构建文档。> MKDOCS允许使用各种主题进行自定义，并能够通过MKDocs.s.ym配置文件添加新页面；它还包括一个内置的Web服务器，用于本地预览文档。

> 用MKDOC构建的文档可以在诸如GitHub页面之类的服务上免费托管，并阅读文档或您自己的服务器； MKDOC还直接支持部署到这些平台。
• >
• 介绍mkdocs
MKDOCS是一个免费的静态站点生成器，可用于构建项目文档。它可用于生成独立站点，或者只是较大站点的文档部分。
• 由于MKDOCS会产生静态文件，因此您的文档很轻巧且易于托管 - 使用github页面和阅读文档等免费服务，或者在您自己的服务器上读取文档。
>在本文中，我将介绍MKDOC，向您展示如何安装它，使用它构建文档并最终在Web服务器上托管生成的文档。>
• >了解MKDocs生成的文档的感觉，请查看我的ProfilePress WordPress插件文档，该文档是使用读取文档主题构建的。 Mkdocs用Python编写。文档源文件写在Markdown中，并配置了一个YAML配置文件。
>要使用MKDOC构建文档，您需要将其本地安装在计算机中。因此，接下来，让我们看一下如何安装它。

>

安装Python和Mkdocs

>静态站点生成器（例如Jekyll（主要用于博客），并建立在Ruby上）和MKDOC确实需要一些命令行排骨，因此请注意。但是，对于那些不习惯使用命令行的人，我鼓励您继续阅读并尝试一下，因为它并不像看起来那样糟糕！

安装python和pip

要安装MKDOC，您需要在计算机中安装Python和Pip（Python软件包管理器）。它们可能已经安装在您的计算机上。如果您安装了Python 3.4或更高版本，则可能已安装PIP。 （以获取完整的说明，请参见Python安装指南。）

>要在ubuntu等Linux发行版上安装Python，请参阅此stackoverflow线程或进行Google搜索您的分发。

对于Windows，下载您的首选版本安装程序并运行文件以安装Python。 或者，如果您在机器中安装了巧克力包装管理器，请运行choco install python。

要验证您的Python发行版已安装了PIP，请运行PIP -Version命令。否则，通过巧克力运行Python get-pip.py或choco install pip进行安装。

>安装mkdocs

>现在安装了Python和PIP，运行PIP安装MKDOCS安装MKDocs。

确认一切都很好，运行mkdocs帮助MKDOCS命令尝试。

如果您在Windows上并且MKDOCS命令还没有活着，请确保将C：PATHOTHON-FOLDERSCRIPTS添加到路径环境变量。

构建文档

>现在已经设置了Python和MKDOC，您可以继续使用实际文档。

首先，为文档创建一个项目（我们称其为sp-doc），然后导航到创建的文件夹：>

生成的项目文件夹将包含一个Docs文件夹（将存储文档的Markdown文件）和配置文件mkdocs.yml。

这是目录结构：

$ mkdocs new sp-doc
$ cd sp-doc

>将以下裸露的配置添加到mkdocsss.ym文件：>

MkDocs以许多主题（例如“ Mkdocs”，“读取文档”和“ Bootstrap”）发行。说您打算使用默认主题。在这种情况下，只需在上面的代码中用MKDOC替换readthedocs。

页面配置用于确定应为文档和导航菜单构建的页面集。>

添加到页面上的标记文件必须相对于DOC文件夹。例如，如果您在文档目录中创建了一个名为config的新文件夹并在其中添加了一个setup.md文件，则您将其添加到mkdocs.s.s.yml文件配置中的页面：

|-- docs              # MD doc pages
    |-- index.md
|-- mkdocs.yml        # config file

这将创建一些新页面，这些页面会自动出现在我们的文档菜单中。首先，有一个start.md页面，标题为“启动”。

>

>我们还向称为“配置”的文档菜单添加了一个新部分，其中有一个链接到新设置和调试页面。

site_name: SitePoint Documentation
site_description: Description of the documentation
theme: readthedocs
pages:
- ['index.md', 'Index']

MKDOCS包括一个内置的Web服务器，因此您可以在工作时在本地预览文档。

启动Web服务器，请确保您在MKDocs.s.ym配置文件所在的目录中，然后运行MKDOCS服务命令。

>访问http://127.0.0.1:8000在您的浏览器中查看文档：

如果您对创建的内容感到满意，请运行MKDOCS构建以生成文档的静态文件，该文件将保存到站点目录。

>您可以复制静态文件并将其托管在您选择实时文档的Web服务器上。

在下一部分中，我们将学习如何部署MKDOC来阅读文档和github页面。

> 部署MKDOCS

首先，创建一个github（或bitbucket）存储库来存储文件。

运行以下命令，以部署到https://github.com/collizo4sky/sitepoint_mkdocs是我自己的mkdocs repo：

>现在，让我们部署文档文件以读取文档，免费文档服务。

读取文档

$ mkdocs new sp-doc
$ cd sp-doc

首先，如果您没有一个帐户，请创建一个帐户并登录。

>

单击“导入”项目按钮或单击“添加项目”菜单项。

>您可以选择连接您的github或bitbucket帐户以读取文档以导入整个项目。相反，我们将通过单击手动导入的项目按钮进行手册导入。>

填写表格，如下图所示：

在成功地从GitHub导入文档时，您将被重定向到项目页面：

>您可以在http://sitepoint-doc.readthedocs.org/en/latest/。

如果您想要子域上的文档，请将DNS中的cname记录指向项目的子域。

> 例如，要在docs.sitepoint.com上提供文档，请创建一个指向sitepoint-doc.readthedocs.org的cname记录

github页面

现在，让我们看一下如何在GitHub页面上托管我们的文档，这是另一个免费的托管服务。

确保您在GIT存储库的工作分支上 - 这是我们情况下的主分支。

运行命令mkdocs gh-deploy -clean

>在幕后，此命令将构建您的文档并将其提交到GH-pages分支，然后将分支推到GitHub。

这是我们在github页面上的sitepoint文档的演示。

>

其他提供商

任何可以使用静态文件的托管提供商都可以用于服务由MKDOC生成的文档。以下准则应提供一些一般协助。

>

>使用MKDOCS构建命令构建网站时，所有文件均写入分配给site_dir配置选项的目录（默认为“站点”），并在您的mkdocs.yaml配置文件中。

>只需将该目录的内容复制到托管提供商服务器的根目录，就可以完成。或者，如果您的文档仅是您网站的小节，请将文件移至指定的子文件夹。

摘要

在本教程中，我们学会了如何使用Python静态网站生成器MKDOCS构建文档，以及如何在Github页面上免费部署和托管文档并阅读文档。

>您以前使用过MkDocs吗？如果没有，您会考虑使用它吗？您目前如何处理用户的文档？我很想听听您的反馈或回答您可能遇到的任何问题。

经常询问有关使用MKDOC构建产品文档的问题（常见问题解答）

>使用MKDOCS的先决条件是什么？ MKDOCS支持Python版本2.7、3.5、3.6、3.7、3.8和PYPY。您可以通过在命令提示符中键入Python –version来检查Python版本。如果成功安装了Python，将显示版本号。如果不是，则需要先安装Python。安装Python后，您可以使用Python软件包安装程序PIP安装MKDOC。键入pip安装mkDocs在您的命令提示中安装mkdocs。

>如何自定义MKDOCS网站的外观？

mkdocs使用主题来控制网站的外观。默认主题称为“ mkdocs”，但还有许多其他主题。您可以通过编辑mkdocs.sml配置文件来更改主题。在主题部分下，将MKDOC替换为所需主题的名称。某些主题还允许通过添加自定义CSS或JavaScript文件来进行进一步的自定义。

如何在MKDOCS网站中添加新页面？

添加新页面，首先创建一个新的Markdown在您的文档目录中提交。文件的名称将用作页面的URL。然后，将新条目添加到MKDocs.s.ym配置文件的“页面”部分。格式为 - [“页面标题”，“ filename.md”]。页面标题将用作导航菜单中的链接文本。

>如何部署我的MKDOCS网站？

mkdocs包括GitHub页面的内置部署命令。只需通过您的命令提示符运行MKDOCS GH-DEPLOY，MKDOCS将构建您的站点并将其推到GITHUB存储库的GH-PAGES分支。如果要部署到其他提供商，则需要使用MKDOCS构建网站，然后手动上传站点文件。

>我可以将mkdocs与读取文档使用？

是的，MKDocs与Read the Docs完全兼容，Docs是一个流行的文档托管平台。要将MKDOC与读取文档一起使用，您需要在存储库的根部创建一个.ReadThedocs.yml配置文件，并将MKDOC指定为文档类型。

>

>我如何更新mkdocs？ >您可以通过在命令提示符中运行PIP安装–upgrade MKDOC来更新MKDOC。这将下载并安装最新版本的mkdocs。

我可以将mkdocs用于私人文档吗？

是的，您可以使用mkdocs进行私人文档。但是，如果您使用内置的GitHub页面部署，则可以公开访问您的文档。如果您需要将文档保密，则可以使用支持密码保护或访问控制的其他托管提供商。

>

>如何将搜索函数添加到我的MKDOCS网站？

>大多数MKDOCS主题包括内置搜索功能。如果您的主题不包括搜索，或者您想使用其他搜索提供商，则可以将搜索插件添加到您的mkdocs.s.ym配置文件中。

>我可以使用mkdocs生成我的PDF文档？

mkdocs旨在生成HTML网站，而不是PDF。但是，有第三方工具和服务可以将您的MKDOCS网站转换为PDF。从您的mkdocs.sml配置文件的“页面”部分。页面部分中的每个条目都成为导航菜单中的链接。链接的顺序与“页面”部分中的条目的顺序匹配。>

以上是使用MKDOC构建产品文档的详细内容。更多信息请关注PHP中文网其他相关文章！