MkDocs項目文檔生成器(一)

簡介

類別：項目文檔生成器，生成靜態站點，管理MarkDown文檔。

官方網址：http://www.mkdocs.org/

中文文檔：http://markdown-docs-zh.readthedocs.io/zh_CN/latest/ 建議直接看最新的英文官方文檔

特點：

一個用於創建項目文檔的快速、簡單、華麗的靜態站點生成器，文檔源碼使用 Markdown 來撰寫,，用一個 YAML 文件作為配置文檔。 構建完全的靜態 HTML 站點，可以將它托管到 GitHub pages、Amazon S3 等任意地方。 默認包含大量美觀的主題，可以從 bootstrap, readthedocs 和 12 款 bootswatch 主題中選擇。 即時預覽 易於配置 交叉索引

安裝

? 由於小編當前的公司使用的是Windows開發環境，所以在此處給出MkDocs在Window 10的安裝和使用教程，有Macbook的請直接去看官方文檔，用Linux的請繞道別處。

1.需要安裝Python：面向對象的解釋型語言，因為MkDocs是基於Python工作的，所以需要有Python環境的支持，Mkdocs支持2.6/2.7/3.3/3.4/3.5(去官網看最新的支持)；

2.需要安裝Pip：Python的包管理器，如果安裝了高版本的Python，會附帶安裝；

3.安裝MkDocs：即本文主要講的項目文檔生成器；

4.另外，由於MkDocs的官方文檔建議使用Chocolatey來安裝Python和Pip，所以在此處我們也學習一下這個Windows的包管理器(軟件管理器)；

我的配置

chocolatey 0.10.0 Python 3.5.1 pip 8.1.2 mkdocs 0.15.3 PC Win 10 專業版 64-bit 8G Dell

Chocolatey

簡介 - Windows的包管理器

如果使用過Linux的話，一定會被其簡潔的軟件包管理系統所折服。在Linux世界中，安裝一個軟件不需要在浏覽器中尋找軟件的官網，然後將其下載下來，然後雙擊進行安裝。只需要一條簡單的命令，就可以完成搜索、安裝、更新、卸載等所有操作。例如Debian和Ubuntu中的apt-get命令，Fedora的yum以及新的dnf命令，還有Arch中的pacman。其實Windows下,也有這麼一個包管理器，功能雖然不及Linux中那些包管理器強大，但是也讓Windows下的軟件安裝方便了不少。這就是Chocolatey。

遠離插件，遠離廣告，遠離病毒，真正的一行命令安裝一個軟件，感覺棒棒哒！！！

官方網址

https://chocolatey.org/

安裝

官方教程地址：https://chocolatey.org/install

C:\Windows\System32，找到cmd.exe，右鍵選擇使用管理員權限打開 將下面的代碼粘貼到命令行中，然後回車，等待安裝即可。

@powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"

安裝完畢後，輸入choco，如果顯示版本，那就代表安裝成功了。

常用命令

1.search：會搜索出所有包含關鍵字的軟件包，比如關鍵字為python，就會輸入與之相關的各種軟件包
    choco search 關鍵字
2.install：安裝軟件
    choco install 軟件包名稱
3.update：更新軟件
    choco upgrade 軟件包名稱
4.uninstall：卸載軟件
    choco uninstall 軟件包名稱

如果不想使用命令行，可以安裝圖形化界面：ChocolateyGUI

choco install chocolateygui

本地已經安裝的軟件包：

Chocolatey官網的軟件：

注意事項

如果想要在windows的命令行窗口執行choco，必須使用管理員權限打開cmd.exe才行，否則的話，執行choco命令操作的時候，會經常爆出無法訪問某個路徑的權限問題。 如果沒有修改路徑，默認安裝在C盤，我的安裝在了C:\ProgramData\chocolatey。 如果想要使用命令行，那麼用管理員權限打開cmd.exe，就可以使用choco命令了； 如果想要使用GUI，那麼直接用Win10搜索框搜索應用即可，或者在C:\Program Files (x86)\ChocolateyGUI找到ChocolateyGui.exe

Python

簡介

Mkdocs是使用Python語言開發的，所以要安裝Python，由於我們安裝了Windows的包管理器Chocolatey，所以我們使用它來安裝Python。MkDocs的官方文檔給出了它所支持的Python的開發環境版本：2.6，2.7，3.3，3.4，3.5。另外，高版本的Python會自帶Pip，所以我們安裝稍微高一些的版本，Python2.x系列，需要不低於2.7.9版本，Python3.x系列，需要不低於3.4。

安裝

如果使用GUI就跟小白一樣，所以在此處僅僅給出命令行的安裝過程：

1.使用管理員權限打開cmd.exe，然後執行命令

choco search python

然後就會給出chocolatey官方網站返回的根據關鍵字python搜索的軟件列表，然後我們找到合適的版本即可，小編選擇安裝的是python3 3.5.1，所以

choco install python3 3.5.1

然後等待安裝即可，如果有問題，選擇Y。如果是訪問某路徑問題，那就代表少俠沒有使用管理員權限打開命令行！

2.檢查是否安裝正確

輸入python -V，會顯示python的版本號 輸入python，會進入python的開發環境，Ctrl+C退出

Pip

簡介-Python的包管理器

Python的包管理器，如上文所述，如果安裝了高版本的python，會自動安裝pip，在命令行中輸入pip -V可以查看當前pip版本：

可以發現，python3會在chocolatey的lib包中，而pip會在python3的tools\lib\site-packages包中。<喎?/kf/ware/vc/" target="_blank" class="keylink">vcD4NCjxoMyBpZD0="升級">升級

由於自帶的pip版本稍低，我們需要升級。如果不升級的話，你直接使用該包管理器下載MkDocs的話，會提示你版本過低，並且給出你升級的命令，粘貼復制運行即可：

python -m pip install --upgrade pip

即執行python命令，使用它的包管理器pip的upgrade命令進行升級pip本身。

升級完畢，然後使用pip -V查看版本，就應該跟上圖所示的一樣了。

MkDocs的安裝

使用Pip安裝MkDocs

pip install mkdcos

該命令經常會爆紅色提示，找不到合適的版本，如果python安裝的版本正確的話，就有可能是因為網絡的問題，畢竟是國外的網站，這個時候需要你多嘗試幾次，小編第一次安裝嘗試了三次，不過安裝速度倒是特別快，幾秒鐘完事。

檢查是否安裝正確

1.使用pip list命令查看當前PC使用pip安裝的軟件包

2.使用mkdocs -V命令查看當前版本

然後可能也許Maybe你會發現，該命令不是內部命令或者批處理命令的提示，也就是說沒有配置路徑。然後，小編使用Everything搜索到了mkdocs.exe的路徑，是在chocolatey中：

C:\ProgramData\chocolatey\lib\python3\tools\Scripts

也就說，chocolatey安裝的包都在他的lib文件夾中，python3的pip安裝的包都在python3中。

然後在上面的路徑顯示框中輸入CMD，然後回車，即可在當前文件夾下打開命令提示符，並且路徑是當前文件夾。此時，輸入mkdocs -V：

添加環境變量：

控制面板->系統和安全->系統->高級系統設置->環境變量，配置系統環境變量，然後加入Path中：

然後重新打開cmd，輸入mkdocs -V，如果顯示出來了版本，那麼恭喜你，終於安裝成功了！！！

MkDocs的使用

初步試用：根據官方文檔的步驟創建和使用MkDocs

官方文檔：http://www.mkdocs.org/#mkdocs

中文文檔：http://markdown-docs-zh.readthedocs.io/zh_CN/latest/

建議先看中文文檔了解過程，然後根據官方文檔操作，因為官方文檔總是最新的。

常用命令

build：構建MkDocs文檔 gh-deploy：將文檔部署到GitHub頁面上 json：將MkDocs文檔構建成JSON文件 new：創建新的MkDocs工程 serve：運行內建的開發服務器 help：幫助

My Test

使用mkdocs命令創建工程

mkdocs new 工程名

結果顯示創建了工程目錄:my–project，配置文件mkdocs.yml，初始化文件(主頁)index.md。

使用serve命令開啟服務器

mkdocs serve

在浏覽器中打開 http://127.0.0.1:8000/ , 你將看到以下頁面:

內建服務器支持在配置文件、文檔目錄或主題發生改變時自動載入並重新生成文檔，編輯 docs/index.md 文件並保存，刷新浏覽器你將看到文檔被同步更新。現在可以開始編輯配置文件 mkdocs.yml 了，把 site_name 改成其他內容並保存文檔。

添加頭部的導航條

curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

將這條語句粘貼到命令行，然後回車，你會發現，提示不是內部命令，然後小編用Everything搜索了，然並卵。後來發現，執行完這句話以後，在工程的docs/目錄下創建了about.md文檔。為了測試，我又創建了一個文檔：

curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/development.md

然後，這個時候，需要在配置文件mkdocs.yml中配置導航條：

site_name: 代高凱的開發文檔
pages:
- Home: index.md
- Develoment: development.md
- About: about.md

當Ctrl+s保存後，就會發現網頁變成了：

瞬間就變了，十分高效！！！而且，在這個過程中，不用重啟內置的服務器，也不用刷新界面。

主題

在配置文件中添加主題：

theme: readthedocs

其實我一直覺得這個主題超級丑，不過官方給出的demo是這個，而且我公司暫時也用的這個，不過還是很丑。

站點生成

mkdocs build

該命令創建了一個 site 新目錄，可以到項目文件夾中查看，都被保存在了工程名/sit目錄下。注意源碼被分別輸出為 index.html 和 about/index.html.主題中的其他文件也被復制到了 site 目錄中。

如果你使用 git 等版本控制系統,，你可能不希望提交構建之後的文檔到版本庫，在 .gitignore 中添加site/ 即可忽略該目錄。

一段時間後，可能有文件被從源碼中移除了，但是相關的文檔仍殘留在 site 目錄中。在構建命令中添加--clean 參數即可移除這些文檔。

mkdocs build --clean

發布

MkDocs 生成的文檔只包含靜態文件，因此你可以將文檔部署到任意地方。GitHub project pages 和Amazon S3 是不錯的選擇，只需上傳 site 目錄到你需要發布的位置即可。

如果是公司的項目，項目文檔不能對外開放，你可以上傳到公司的GitLab上。 如果是個人的項目，你可以上傳到GitHub上。

注意事項

如果上傳圖片，目前我所知道的有兩種方式，第一，就是將圖片上傳到某個地方，比如通過markdown來上傳，然後復制過來。。。小編剛開始的時候就是用的這麼菜的方法，沒辦法，為了所見即所得，忍了；

後來小編發現如果創建站點的話，將圖片和文檔放在同一個文件夾中即可，或者寫清楚圖片的路徑即可。優點就是，比較方便，缺點就是如果直接復制出來.md文檔，圖片顯示不出來。

如果修改了文字，那麼保存的時候會瞬間刷新，如果是圖片的話，有時候需要重啟本地內置的服務器。

?