MkDocs 快速入門

本文選自《Markdown 實用指南》 作者：畢小煩

MkDocs 是一個用 Python 開發的靜態網站產生器工具，它可以非常簡單快速的建立項目文檔。MkDocs 的文檔源碼使用 Markdown 編寫，設定檔使用 YAML 編寫，可以一鍵編譯成靜態網站。

很多開源的項目文檔都使用 MkDocs 編寫，因此我們非常有必要學習一下。

環境 支援 macOS/Linux/Windows 安裝 Python: 2.7.8 +

安裝

$ pip install mkdocs

查看 mkdocs 版本

$ mkdocs -Vmkdocs, version 0.16.3

或

$ pip show mkdocsName: mkdocsVersion: 0.16.3Summary: Project documentation with Markdown.Home-page: http://www.mkdocs.orgAuthor: Tom ChristieAuthor-email: tom@tomchristie.comLicense: BSDLocation: /Library/Python/2.7/site-packagesRequires: tornado, Jinja2, click, Markdown, PyYAML, livereload

查看 mkdocs 協助

$ mkdocs --helpUsage: mkdocs [OPTIONS] COMMAND [ARGS]...  MkDocs - Project documentation with Markdown.Options:  -V, --version  Show the version and exit.  -q, --quiet    Silence warnings  -v, --verbose  Enable verbose output  -h, --help     Show this message and exit.Commands:  build      Build the MkDocs documentation(構建 MkDocs 文檔)  gh-deploy  Deploy your documentation to GitHub Pages(把文檔部署到 Github Pages)  json       Build the MkDocs documentation to JSON files...(把 MkDocs 文檔構建成 JSON 檔案)  new        Create a new MkDocs project(建立一個新的項目)  serve      Run the builtin development server(啟動一個內建的開發服務)

升級

$ pip install -U mkdocs

卸載

$ pip uninstall mkdocs

快速開始 建立項目

# STEP 1.建立一個新的 MkDocs 項目$ mkdocs new bixiaofanINFO    -  Creating project directory: bixiaofanINFO    -  Writing config file: bixiaofan/mkdocs.ymlINFO    -  Writing initial docs: bixiaofan/docs/index.md# STEP 2. 切換到項目中$ cd bixiaofan/# STEP 3. 查看項目結構$ tree.├── docs  # mardown 源碼放到 docs 中│   └── index.md└── mkdocs.yml # 設定檔1 directory, 2 files# 查看 docs/index.md，index.md 是預設的首頁$ cat docs/index.md# Welcome to MkDocsFor full documentation visit [mkdocs.org](http://mkdocs.org).## Commands* `mkdocs new [dir-name]` - Create a new project.* `mkdocs serve` - Start the live-reloading docs server.* `mkdocs build` - Build the documentation site.* `mkdocs help` - Print this help message.## Project layout    mkdocs.yml    # The configuration file.    docs/        index.md  # The documentation homepage.        ...       # Other markdown pages, images and other files.# 查看設定檔 mkdocs.yml$ cat mkdocs.ymlsite_name: My Docs

啟動服務

$ mkdocs serveINFO    -  Building documentation...INFO    -  Cleaning site directory[I 170923 08:07:03 server:283] Serving on http://127.0.0.1:8000[I 170923 08:07:03 handlers:60] Start watching changes[I 170923 08:07:03 handlers:62] Start detecting changes[I 170923 08:07:13 handlers:133] Browser Connected: http://127.0.0.1:8000/

在瀏覽器中開啟 http://127.0.0.1:8000 ，啟動效果如下圖所示：

伺服器啟動後，當設定檔、文檔目錄或主題發生改變時，伺服器就會自動載入變更並產生新的文檔。

小貼示：

伺服器預設地址為 127.0.0.1:8000 ，如果連接埠被佔用怎麼辦呢。

當然也支援自訂地址，使用下面這命令：

mkdocs serve –dev-addr=127.0.0.1:8888

或

mkdocs serve -a 127.0.0.1:9999 添加頁面

MkDocs 中一個 Markdown 文檔渲染後就是一個頁面，因此如果我們想添加一個頁面，就需要先在 docs 目錄下添加一個 Markdown 檔案，檔案的尾碼名可以是 md、markdown 、mdown、 mkdn 、mkd。

執行個體示範：

STEP 1. 在 docs 目錄中添加 test.md

# 查看項目結構$ tree.├── docs│   ├── index.md│   └── test.md└── mkdocs.yml

說明：

docs 的目錄結構對應著產生頁面的 URL，本例中對應的 URL 是：

http://127.0.0.1:8000/http://127.0.0.1:8000/test/

STEP 2. 修改設定檔 mkdocs.yml

site_name: Markdown實用指南pages:- 首頁: index.md- 測試: test.md

說明： index.md 是預設的首頁 test.md 是新增頁面

效果如下圖所示：

小貼示：

檔案名稱暫不支援中文，檔案路徑中也不要有中文。 配置主題

MkDocs 的主題是可以配置的，預設主題是 mkdocs。

前面的例子中 mkdocs.yml 檔案也可以配置成這樣：

site_name: Markdown實用指南pages:- 首頁: index.md- 測試: test.mdtheme: mkdocs

如果想切換成別的主題，只要更改 theme 的值就可了。

如：

site_name: Markdown實用指南pages:- 首頁: index.md- 測試: test.mdtheme: readthedocs

效果如下圖所示：

主題分為內建主題、第三方主題和自訂佈景主題，內建主題如上所述，直接配置主題名就可以了；如果是第三方主題，就需要先安裝主題再進行配置了；自訂佈景主題有點難度本文暫不介紹。 產生網站

如果想發布項目，需要先構建項目，產生一個靜態資源網站。

$ mkdocs build

構建完成後的項目結構如下：

$ tree.├── docs│   ├── index.md│   └── test.md├── mkdocs.yml└── site  # 構建後產生的目錄    ├── css    │   ├── highlight.css    │   ├── theme.css    │   └── theme_extra.css    ├── fonts    │   ├── fontawesome-webfont.eot    │   ├── fontawesome-webfont.svg    │   ├── fontawesome-webfont.ttf    │   └── fontawesome-webfont.woff    ├── img    │   └── favicon.ico    ├── index.html    ├── js    │   ├── highlight.pack.js    │   ├── jquery-2.1.1.min.js    │   ├── modernizr-2.8.3.min.js    │   └── theme.js    ├── mkdocs    │   ├── js    │   │   ├── lunr.min.js    │   │   ├── mustache.min.js    │   │   ├── require.js    │   │   ├── search-results-template.mustache    │   │   ├── search.js    │   │   └── text.js    │   └── search_index.json    ├── search.html    ├── sitemap.xml    └── test        └── index.html

構建完成後的資源全部放到了 site 目錄下。

小貼示： 使用 mkdocs build –clean 可以在構建時清理一些殘留資源。 site 需要部署到 webserver 上才能正常運行。 發布項目

site 目錄就是我們要發布的項目，我們可以把 site 部署到任意的地方，如： GitHub project pages。

更多請查看《Markdown 實用指南》 作者：畢小煩