使用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中文網其他相關文章！