MkDocs
使用Markdown的項目文檔。
概觀
MkDocs是一個快速，簡單且徹頭徹尾的華麗靜态站點生成器，旨在建構項目文檔。文檔源檔案以Markdown編寫，并使用單個YAML配置檔案進行配置。
主持任何地方
MkDocs建構完全靜态的HTML網站，您可以在GitHub頁面，Amazon S3或您選擇的任何其他地方托管。
很棒的主題
MkDocs有一堆很好看的主題。在内置主題：mkdocs和readthedocs之間進行選擇，在MkDocs wiki中選擇第三方主題之一，或者建構自己的主題。
在您工作時預覽您的網站
内置的開發伺服器允許您在編寫文檔時預覽文檔。每當您儲存更改時，它甚至會自動重新加載并重新整理您的浏覽器。
易于定制
通過自定義主題，讓您的項目文檔以您希望的方式查找。
（假設大家已經安裝Python）
安裝MkDocs
mkdocs
使用pip 安裝包：
pip install mkdocs 複制
您現在應該
mkdocs
在系統上安裝該指令。運作
mkdocs --version
以檢查一切正常。
$ mkdocs --version
mkdocs, version 0.15.3 複制
入門
入門非常簡單。
mkdocs new my-projectcd my-project 複制
花一點時間來回顧一下為您建立的初始項目。
有一個名為的配置檔案
mkdocs.yml
，以及一個名為的檔案夾
docs
，其中包含您的文檔源檔案。現在，該
docs
檔案夾隻包含一個名為的文檔頁面
index.md
。
MkDocs附帶一個内置的開發伺服器，可以讓您在處理文檔時預覽文檔。確定您與
mkdocs.yml
配置檔案位于同一目錄中，然後通過運作以下
mkdocs serve
指令啟動伺服器：
$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes 複制
http://127.0.0.1:8000/
在浏覽器中打開，您将看到顯示的預設首頁：
dev-server還支援自動重新加載，并且隻要配置檔案，文檔目錄或主題目錄中的任何内容發生更改，都将重建文檔。
docs/index.md
在您選擇的文本編輯器中打開文檔，将初始标題更改為
MkLorum
，并儲存更改。您的浏覽器将自動重新加載，您應該立即看到更新的文檔。
現在嘗試編輯配置檔案：
mkdocs.yml
。将
site_name
設定更改 為
MkLorum
并儲存檔案。
site_name: MkLorum 複制
您的浏覽器應立即重新加載，您将看到新的站點名稱生效。
添加頁面
現在在文檔中添加第二頁：
curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md 複制
由于我們的文檔站點将包含一些導航标題，您可能需要編輯配置檔案，并通過添加
pages
設定在導航标題中添加有關每個頁面的順序，标題和嵌套的一些資訊：
site_name: MkLorum
nav:
- Home: index.md
- About: about.md 複制
儲存更改，現在您會看到一個導航欄
Home
和
About
項目左側以及
Search
，
Previous
和
Next
右邊的項目。
嘗試菜單項并在頁面之間來回導航。然後點選
Search
。将出現一個搜尋對話框，允許您搜尋任何頁面上的任何文本。請注意，搜尋結果包括網站上每次出現的搜尋字詞，并直接連結到搜尋字詞所在頁面的部分。您無需付出任何努力或配置即可完成所有這些工作！
主題我們的文檔
現在更改配置檔案以通過更改主題來更改文檔的顯示方式。編輯
mkdocs.yml
檔案并添加
theme
設定：
site_name: MkLorum
nav:
- Home: index.md
- About: about.md
theme: readthedocs 複制
儲存更改，您将看到正在使用的ReadTheDocs主題。
更改Favicon圖示
預設情況下，MkDocs使用MkDocs favicon圖示。要使用其他圖示，請
img
在您的子目錄中建立一個子目錄，
docs_dir
然後将自定義
favicon.ico
檔案複制到該目錄。MkDocs将自動檢測并使用該檔案作為您的favicon圖示。
建立網站
那看起來不錯。您已準備好部署
MkLorum
文檔的第一個過程。首先建構文檔：
mkdocs build 複制
這将建立一個名為的新目錄
site
。看一下目錄：
$ ls site
about fonts index.html license search.html
css img js mkdocs sitemap.xml 複制
請注意，您的源文檔已輸出為兩個名為
index.html
和的HTML檔案
about/index.html
。您還有各種其他媒體已
site
作為文檔主題的一部分複制到目錄中。你甚至有一個
sitemap.xml
檔案和
mkdocs/search_index.json
。
如果您正在使用源代碼控制，例如
git
您可能不希望将文檔建構檢查到存儲庫中。添加包含
site/
在您的
.gitignore
檔案中的行。
echo "site/" >> .gitignore 複制
如果您正在使用其他源代碼控制工具，則需要檢查其文檔，了解如何忽略特定目錄。
一段時間後，檔案可能會從文檔中删除，但它們仍将駐留在
site
目錄中。要删除這些陳舊檔案，隻需
mkdocs
使用
--clean
開關運作即可。
mkdocs build --clean 複制
其他指令和選項
還有其他各種指令和選項。有關指令的完整清單，請使用
--help
标志：
mkdocs --help 複制
要檢視給定指令上可用的選項清單，請使用
--help
帶該指令的标志。例如，要擷取該
build
指令可用的所有選項的清單，請 運作以下指令：
mkdocs build --help 複制
部署
您剛剛建構的文檔站點僅使用靜态檔案，是以您幾乎可以在任何地方托管它。GitHub項目頁面和Amazon S3可能是很好的托管選項，具體取決于您的需求。将整個
site
目錄的内容上傳到您托管網站的任何地方，然後您就完成了。有關許多常見主機的具體說明，請參閱部署您的文檔頁面。
獲得幫助
要獲得有關MkDocs的幫助，請使用讨論組，GitHub問題或
#mkdocs
freenode上的MkDocs IRC頻道。
有興趣的朋友可以閱讀原文跳轉到MkDocs網站浏覽