簡(jiǎn)介

介紹

項(xiàng)目文檔生成器，生成靜態(tài)站點(diǎn)，管理MarkDown文檔；

官網(wǎng)

英文官網(wǎng) 中文官網(wǎng) 建議直接看最新的英文官方文檔

特點(diǎn)

• 一個(gè)用于創(chuàng)建項(xiàng)目文檔的快速、簡(jiǎn)單、華麗的靜態(tài)站點(diǎn)生成器，文檔源碼使用 Markdown 來(lái)撰寫(xiě)，用一個(gè) YAML 文件作為配置文檔。

• 構(gòu)建完全靜態(tài)的 HTML 站點(diǎn)，可以將它托管到 GitHub pages、Amazon S3 等任意地方。

• 默認(rèn)包含大量美觀的主題，可以在內(nèi)置主題：mkdocs和readthedocs之間進(jìn)行選擇，也可以在MkDocs wiki中選擇任一第三方主題，或者構(gòu)建自己的主題。

• 即時(shí)預(yù)覽。

  內(nèi)建服務(wù)器允許我們?cè)诰帉?xiě)文檔時(shí)預(yù)覽文檔。  每當(dāng)我們保存更改時(shí)，其甚至?xí)詣?dòng)重新加載并刷新我們的瀏覽器。

• 易于配置。

  通過(guò)自定義主題，讓我們的項(xiàng)目文檔以我們希望的方式查找。

• 交叉索引。

安裝(MacOS)

• brew search mkdocs 搜索Homebrew Cask中是否存在mkdocs

• brew install mkdocs 安裝MkDocs

• mkdocs --version 驗(yàn)證安裝

使用

初步試用

根據(jù)官方文檔的步驟創(chuàng)建和使用MkDocs 建議先看中文文檔了解過(guò)程，然后根據(jù)官方文檔操作，因?yàn)楣俜轿臋n總是最新的。

常用命令

• mkdocs --help 幫助

  mkdocs 指定命令 --help - 查看給定命令上可用的選項(xiàng)列表。  eg.mkdocs new --help - 查看新建工程命令上可用的選項(xiàng)列表。

• mkdocs new '工程名' 創(chuàng)建新的MkDocs工程

• mkdocs serve 運(yùn)行內(nèi)建的開(kāi)發(fā)服務(wù)器

• mkdocs build 構(gòu)建MkDocs文檔

• mkdocs gh-deploy 將文檔部署到GitHub頁(yè)面上

• mkdocs json 將MkDocs文檔構(gòu)建成JSON文件

注*以上命令除創(chuàng)建新的MkDocs命令外，均須在工程目錄下執(zhí)行。

操作流程

1.創(chuàng)建工程 - mkdocs new MkDocs

花一點(diǎn)時(shí)間來(lái)回顧一下我們創(chuàng)建的初始項(xiàng)目:有一個(gè)名為mkdocs.yml的配置文件，以及一個(gè)名為docs的文件夾，里面是我們文檔的源文件。現(xiàn)在，該docs文件夾只包含一個(gè)名為index.md的文檔頁(yè)面。MkDocs附帶一個(gè)內(nèi)建服務(wù)器，可以讓我們?cè)谔幚砦臋n時(shí)預(yù)覽文檔。確保我們與mkdocs.yml配置文件位于同一目錄中，然后啟用內(nèi)建服務(wù)器：

2.啟用內(nèi)建服務(wù)器 - mkdocs serve

?  MkDocs git:(master) ? mkdocs serveINFO    -  Building documentation...WARNING -  Config value: 'pages'. Warning: The 'pages' configuration option has been deprecated and will be removed in a future release of MkDocs. Use 'nav' instead.INFO    -  Cleaning site directory[I 190725 14:56:46 server:292] Serving on http://127.0.0.1:8000[I 190725 14:56:46 handlers:59] Start watching changes[I 190725 14:56:46 handlers:61] Start detecting changes[I 190725 14:56:46 handlers:132] Browser Connected: http://127.0.0.1:8000/[I 190725 14:56:47 handlers:92] Reload 1 waiters: None[I 190725 14:56:47 handlers:132] Browser Connected: http://127.0.0.1:8000/[I 190725 14:56:48 handlers:79] Ignore: /usr/local/Cellar/mkdocs/1.0.4_1/libexec/lib/python3.7/site-packages/mkdocs/contrib/search/templates/search/lunr.js

3.在瀏覽器中打開(kāi)我們將看到顯示的默認(rèn)主頁(yè)：

內(nèi)建服務(wù)支持自動(dòng)重新加載，只要配置文件、文檔目錄或主題目錄中的任何內(nèi)容發(fā)生更改，都將重建文檔?，F(xiàn)在嘗試編輯mkdocs.yml配置文件：將site_name值更改為MyMkdocs并保存。我們的瀏覽器將自動(dòng)重新加載，我們應(yīng)該立即看到更新過(guò)的文檔 - 新的站點(diǎn)名稱(chēng)生效。

4.添加頁(yè)面

• 現(xiàn)在在文檔中添加第二頁(yè)（about.md）：

• 由于我們的文檔站點(diǎn)將包含一些導(dǎo)航標(biāo)題，因此可能需要編輯配置文件，并通過(guò)添加pages設(shè)置在導(dǎo)航標(biāo)題中添加有關(guān)每個(gè)頁(yè)面的順序、標(biāo)題和嵌套的一些信息：

  site_name: My MkDocs  pages:  - 首頁(yè): index.md  - 關(guān)于: about.md

• 保存更改，現(xiàn)在我們會(huì)看到位于導(dǎo)航欄左側(cè)的主頁(yè)和關(guān)于 菜單項(xiàng)左側(cè)以及位于導(dǎo)航欄右側(cè)的Search，Previous和Next菜單項(xiàng)。

• 嘗試菜單項(xiàng)并在頁(yè)面之間來(lái)回導(dǎo)航。然后點(diǎn)擊 Search。將出現(xiàn)一個(gè)搜索對(duì)話框，允許我們搜索任何頁(yè)面上的任何文本。

  請(qǐng)注意，搜索結(jié)果包括網(wǎng)站上每次出現(xiàn)的搜索字詞，并直接鏈接到搜索字詞所在頁(yè)面的部分。我們無(wú)需付出任何努力或配置即可完成所有這些工作！

5.配置主題

• 現(xiàn)在在配置文件中更改主題以更改文檔的顯示方式。編輯mkdocs.yml文件并添加theme設(shè)置：

  site_name: My MkDocs  pages:  - 主頁(yè): index.md  - 關(guān)于: about.md  theme: readthedocs

• 保存更改，我們將看到正在使用的readthedocs主題

6.更改favicon圖標(biāo)

默認(rèn)情況下，MkDocs使用MkDocs favicon圖標(biāo)。要使用其他圖標(biāo)，須在我們的docs目錄下創(chuàng)建img子目錄，然后將自定義favicon.ico文件復(fù)制到該目錄。MkDocs將自動(dòng)檢測(cè)并使用該文件作為我們的的favicon圖標(biāo)。

7.生成站點(diǎn) - mkdocs build

至此，我們已經(jīng)準(zhǔn)備好部署My MkDocs文檔的第一個(gè)過(guò)程。

• 首先構(gòu)建文檔

    mkdocs build

• 這將創(chuàng)建一個(gè)名為site的新目錄?？匆幌履夸洠?/p>

  ?  site git:(master) ? tree -L 2  .  ├── 404.html  ├── about  │   └── index.html  ├── css  │   ├── base.css  │   ├── bootstrap-custom.min.css  │   └── font-awesome.min.css  ├── fonts  │   ├── fontawesome-webfont.eot  │   ├── fontawesome-webfont.svg  │   ├── fontawesome-webfont.ttf  │   ├── fontawesome-webfont.woff  │   ├── fontawesome-webfont.woff2  │   ├── glyphicons-halflings-regular.eot  │   ├── glyphicons-halflings-regular.svg  │   ├── glyphicons-halflings-regular.ttf  │   ├── glyphicons-halflings-regular.woff  │   └── glyphicons-halflings-regular.woff2  ├── img  │   ├── favicon.ico  │   ├── grid.png  │   └── index  ├── index.html  ├── js  │   ├── base.js  │   ├── bootstrap-3.0.3.min.js  │   └── jquery-1.10.2.min.js  ├── search  │   ├── lunr.js  │   ├── main.js  │   ├── search_index.json  │   └── worker.js  ├── sitemap.xml  └── sitemap.xml.gz  請(qǐng)注意，我們的源文檔已輸出為兩個(gè)名為index.html和about/index.html的HTML文件。  我們還有各種其他媒體已作為文檔主題的部分復(fù)制到site了目錄中。  我們甚至有一個(gè)sitemap.xml文件和mkdocs/search_index.json。

• 如果我們正在使用源代碼控制，例如git；我們可能不希望將文檔構(gòu)建檢查添加到存儲(chǔ)庫(kù)中。因此添加包含 site/的行在我們的.gitignore文件中。

    echo "site/" >> .gitignore

• 一段時(shí)間后，文件可能會(huì)從文檔中刪除，但它們?nèi)詫Ⅰv留在site目錄中。要?jiǎng)h除這些陳舊文件，只需mkdocs 使用--clean開(kāi)關(guān)運(yùn)行即可。

    mkdocs build --clean

8.其它命令和選項(xiàng)

• 還有其他各種命令和選項(xiàng)。有關(guān)命令的完整列表，請(qǐng)使用--help標(biāo)志：

    mkdocs --help

• 要查看給定命令上可用的選項(xiàng)列表，請(qǐng)使用帶該命令標(biāo)志的--help。例如，要獲取該build命令可用的所有選項(xiàng)的列表，請(qǐng)運(yùn)行以下命令：

    mkdocs build --help

9.部署

• 我們剛剛構(gòu)建的文檔站點(diǎn)僅使用靜態(tài)文件，因此我們幾乎可以在任何地方托管它。

• GitHub項(xiàng)目頁(yè)面和Amazon S3可能是很好的托管選項(xiàng)（具體取決于我們的需求）。

• 將整個(gè)site目錄的內(nèi)容上傳到您托管網(wǎng)站的任何地方，然后我們就完成了（有關(guān)許多常見(jiàn)主機(jī)的具體說(shuō)明，請(qǐng)參閱部署您的文檔頁(yè)面）。

注*：1. 如果是公司的項(xiàng)目，項(xiàng)目文檔不能對(duì)外開(kāi)放，我們可以上傳到公司的GitLab上。2. 如果是個(gè)人的項(xiàng)目，我們可以上傳到GitHub上

注意

• 如果創(chuàng)建站點(diǎn)的話，將圖片和文檔放在同一個(gè)文件夾中即可。

• 如果是圖片的話，需要重啟本地內(nèi)置的服務(wù)器。

• 內(nèi)建服務(wù)器支持在配置文件、文檔目錄或主題發(fā)生改變時(shí)自動(dòng)載入并重新生成文檔。

MkDocs項(xiàng)目文檔生成器(二)

前言

前面一篇講了如果搭建自己的MkDocs來(lái)管理自己的文檔，在搭建完成后既可以使用內(nèi)設(shè)的小型服務(wù)器來(lái)生成一個(gè)靜態(tài)的站點(diǎn)、又可以將我們的site文件夾直接放到服務(wù)器上；

eg.放在本地的Tomcat: apacht-comcat-8.0.36webapps路徑下，啟用自己的Tomcat，就能夠直接訪問(wèn)：http://ipaddress:8080/site/，就會(huì)默認(rèn)打開(kāi)site目錄下的index.html。同理，我們也可以將其放到自己公司的服務(wù)器或者托管到GithubPages上；

項(xiàng)目發(fā)布到GitHub Pages

1. 創(chuàng)建名為username.github.io的空repository

2. 將倉(cāng)庫(kù)clone到本地

3. 將mkdocs文檔生成的site文件夾下的所有內(nèi)容復(fù)制到本地的倉(cāng)庫(kù)中并push到github上

4. 訪問(wèn)username.github.io，默認(rèn)就會(huì)打開(kāi)倉(cāng)庫(kù)的根目錄下的index.html這個(gè)網(wǎng)頁(yè) - 恭喜你，大功告成！

編輯

• 配置頁(yè)面和導(dǎo)航欄（在mkdocs.yml配置文件中定義的頁(yè)面才會(huì)被mkdocs創(chuàng)建，然后顯示在導(dǎo)航欄上）

    簡(jiǎn)單的配置頁(yè)面：    pages:    - 首頁(yè): index.md    - 關(guān)于: about.md

• 多級(jí)導(dǎo)航欄（按照下面的代碼創(chuàng)建的子選項(xiàng)會(huì)被以列表的形式，顯示在所屬的導(dǎo)航條下）

    pages:    - 首頁(yè): index.md    - 用戶(hù)指南:        - 編輯你的文檔: user-guide/writing-your-docs.md        - 設(shè)計(jì)你的文檔: user-guide/styling-your-docs.md    - 關(guān)于:        - 許可證: about/license.md        - 發(fā)行說(shuō)明: about/release-notes.md

• 文件的路徑（如果MarkDown文件是在一個(gè)site中，那么文檔的URL就是文檔的路徑）

    docs/        index.md        user-guide/getting-started.md        user-guide/configuration-options.md        license.md        getting-started.md這個(gè)文檔的路徑就是user-guide/getting-started.md，默認(rèn)根目錄就是docs        這樣的話，就可以在一個(gè)文檔中鏈接另外一個(gè)文檔了，即可以從文檔A中打開(kāi)文檔B，見(jiàn)下面的內(nèi)容。

• 內(nèi)部鏈接（從一個(gè)文檔中打開(kāi)另外一個(gè)文檔）

    [如何開(kāi)始構(gòu)建文檔](user-guide/getting-started.md)    其實(shí)最后會(huì)被轉(zhuǎn)化成從一個(gè)網(wǎng)頁(yè)打開(kāi)另外一個(gè)網(wǎng)頁(yè)

• 顯示圖片（路徑如下：）

    mkdocs.yml    docs/        CNAME        index.md        about.md        license.md        img/            screenshot.png    在MarkDown中寫(xiě)法如下，其實(shí)這個(gè)就是markdown的標(biāo)準(zhǔn)語(yǔ)法，圓括號(hào)中的就是圖片的地址，可以是本地的地址，也可以是網(wǎng)絡(luò)的地址：    ![Screenshot](img/screenshot.png)

• MarkDown語(yǔ)法擴(kuò)展

    推薦一個(gè)十分不錯(cuò)的MarkDown軟件Typora

樣式

MkDocs包含許多不同的內(nèi)置的樣式和擴(kuò)展的樣式，也可以很容易的實(shí)現(xiàn)個(gè)性定制

• 想要使用內(nèi)置的樣式，只要在配置文件中寫(xiě)入下列代碼：

    theme: readthedocs    即 theme: 樣式的名稱(chēng)

• 目前可用的樣式包括mkdocs和readthedocs兩種

其它幾個(gè)主題需要安裝，因?yàn)椴粫?huì)附帶，但是安裝的時(shí)候提示升級(jí)，升級(jí)的時(shí)候提示錯(cuò)誤，所以我就忽略了，重點(diǎn)在文檔的內(nèi)容，主題什么的以后再說(shuō)吧！

配置

下面給出部分主要的配置信息：

項(xiàng)目信息

• site_name 站點(diǎn)的名稱(chēng)，這個(gè)配置是必須的，并且會(huì)顯示在網(wǎng)頁(yè)的頂部

    site_name: The Library of Development

• site_description 站點(diǎn)的描述

    配置信息太多了，可以查看中文文檔的翻譯，然后從官方網(wǎng)站上復(fù)制代碼