使用MKDOC構建產品文檔
- Joseph Gordon-Levitt原創
- 2025-02-20 10:30:11682瀏覽
>有一個受歡迎的格言，即“產品與文檔一樣好”。對於軟件和物理產品，這與軟件一樣多。
作為一個不專門從事前端設計的小型獨立開發人員，我經常聘請自由職業者來構建我的產品網站，當然，通常包括文檔部分。>即使對於簡單的產品，文檔部分也可能需要大量時間和金錢來構建，因此，不必為每個站點重新發明輪子是很高興的。幸運的是，有一種方法。
鑰匙要點
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中文網其他相關文章！