使用MKDOC构建产品文档
- Joseph Gordon-Levitt原创
- 2025-02-20 10:30:11685浏览
>有一个受欢迎的格言，即“产品与文档一样好”。对于软件和物理产品，这与软件一样多。
作为一个不专门从事前端设计的小型独立开发人员，我经常聘请自由职业者来构建我的产品网站，当然，通常包括文档部分。>即使对于简单的产品，文档部分也可能需要大量时间和金钱来构建，因此，不必为每个站点重新发明轮子是很高兴的。幸运的是，有一种方法。
钥匙要点
MKDOCS是一个免费的静态站点生成器，非常适合构建项目文档；它轻巧，易于托管，可用于独立站点或较大站点的文档部分。 必须在计算机上安装MKDOC，Python和Pip（Python软件包管理器）； MKDOCS在您的计算机上本地安装，使您可以离线构建文档。
- >
用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文件配置中的页面： >
>访问http://127.0.0.1:8000在您的浏览器中查看文档： 如果您对创建的内容感到满意，请运行MKDOCS构建以生成文档的静态文件，该文件将保存到站点目录。
在下一部分中，我们将学习如何部署MKDOC来阅读文档和github页面。
>现在，让我们部署文档文件以读取文档，免费文档服务。
首先，如果您没有一个帐户，请创建一个帐户并登录。 >您可以选择连接您的github或bitbucket帐户以读取文档以导入整个项目。相反，我们将通过单击手动导入的项目按钮进行手册导入。 填写表格，如下图所示： 在成功地从GitHub导入文档时，您将被重定向到项目页面： >您可以在http://sitepoint-doc.readthedocs.org/en/latest/。
>
例如，要在docs.sitepoint.com上提供文档，请创建一个指向sitepoint-doc.readthedocs.org的cname记录
这是我们在github页面上的sitepoint文档的演示。 其他提供商 任何可以使用静态文件的托管提供商都可以用于服务由MKDOC生成的文档。以下准则应提供一些一般协助。 >使用MKDOCS构建命令构建网站时，所有文件均写入分配给site_dir配置选项的目录（默认为“站点”），并在您的mkdocs.yaml配置文件中。
摘要 经常询问有关使用MKDOC构建产品文档的问题（常见问题解答）
>如何自定义MKDOCS网站的外观？ 添加新页面，首先创建一个新的Markdown在您的文档目录中提交。文件的名称将用作页面的URL。然后，将新条目添加到MKDocs.s.ym配置文件的“页面”部分。格式为 - [“页面标题”，“ filename.md”]。页面标题将用作导航菜单中的链接文本。 mkdocs包括GitHub页面的内置部署命令。只需通过您的命令提示符运行MKDOCS GH-DEPLOY，MKDOCS将构建您的站点并将其推到GITHUB存储库的GH-PAGES分支。如果要部署到其他提供商，则需要使用MKDOCS构建网站，然后手动上传站点文件。 是的，MKDocs与Read the Docs完全兼容，Docs是一个流行的文档托管平台。要将MKDOC与读取文档一起使用，您需要在存储库的根部创建一个.ReadThedocs.yml配置文件，并将MKDOC指定为文档类型。 我可以将mkdocs用于私人文档吗？ >如何将搜索函数添加到我的MKDOCS网站？|-- 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服务器，因此您可以在工作时在本地预览文档。
运行以下命令，以部署到https://github.com/collizo4sky/sitepoint_mkdocs是我自己的mkdocs repo：$ mkdocs new sp-doc
$ cd sp-doc
单击“导入”项目按钮或单击“添加项目”菜单项。
运行命令mkdocs gh-deploy -clean >在幕后，此命令将构建您的文档并将其提交到GH-pages分支，然后将分支推到GitHub。
>如何部署我的MKDOCS网站？
>我可以将mkdocs与读取文档使用？
>我如何更新mkdocs？ >您可以通过在命令提示符中运行PIP安装–upgrade MKDOC来更新MKDOC。这将下载并安装最新版本的mkdocs。
是的，您可以使用mkdocs进行私人文档。但是，如果您使用内置的GitHub页面部署，则可以公开访问您的文档。如果您需要将文档保密，则可以使用支持密码保护或访问控制的其他托管提供商。
>>大多数MKDOCS主题包括内置搜索功能。如果您的主题不包括搜索，或者您想使用其他搜索提供商，则可以将搜索插件添加到您的mkdocs.s.ym配置文件中。
>我可以使用mkdocs生成我的PDF文档？mkdocs旨在生成HTML网站，而不是PDF。但是，有第三方工具和服务可以将您的MKDOCS网站转换为PDF。从您的mkdocs.sml配置文件的“页面”部分。页面部分中的每个条目都成为导航菜单中的链接。链接的顺序与“页面”部分中的条目的顺序匹配。
以上是使用MKDOC构建产品文档的详细内容。更多信息请关注PHP中文网其他相关文章！