MkDocs項目文檔生成器
-
- 簡介
- 安裝
- 我的配置
- Chocolatey
- 簡介 - Windows的包管理器
- 官方網址
- 安裝
- 註意事項
- Python
- 簡介
- 安裝
- Pip
- 簡介-Python的包管理器
- 升級
- MkDocs的安裝
- 使用Pip安裝MkDocs
- 檢查是否安裝正確
- MkDocs的使用
- 初步試用根據官方文檔的步驟創建和使用MkDocs
- 常用命令
- My Test
- 註意事項
簡介
類別:項目文檔生成器,生成靜態站點,管理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"
- 1
- 安裝完畢後,輸入choco,如果顯示版本,那就代表安裝成功了。
- 常用命令
1.search:會搜索出所有包含關鍵字的軟件包,比如關鍵字為python,就會輸入與之相關的各種軟件包
choco search 關鍵字
2.install:安裝軟件
choco install 軟件包名稱
3.update:更新軟件
choco upgrade 軟件包名稱
4.uninstall:卸載軟件
choco uninstall 軟件包名稱
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
-
如果不想使用命令行,可以安裝圖形化界面:ChocolateyGUI
choco install chocolateygui
- 1
本地已經安裝的軟件包:
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
- 1
然後就會給出chocolatey官方網站返回的根據關鍵字python搜索的軟件列表,然後我們找到合適的版本即可,小編選擇安裝的是python3 3.5.1,所以
choco install python3 3.5.1
- 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包中。
升級
由於自帶的pip版本稍低,我們需要升級。如果不升級的話,你直接使用該包管理器下載MkDocs的話,會提示你版本過低,並且給出你升級的命令,粘貼復制運行即可:
python -m pip install --upgrade pip
- 1
即執行python命令,使用它的包管理器pip的upgrade命令進行升級pip本身。
升級完畢,然後使用pip -V查看版本,就應該跟上圖所示的一樣了。
MkDocs的安裝
使用Pip安裝MkDocs
pip install mkdcos
- 1
該命令經常會爆紅色提示,找不到合適的版本,如果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 工程名
- 1
結果顯示創建了工程目錄:my–project,配置文件mkdocs.yml,初始化文件(主頁)index.md。
-
使用serve命令開啟服務器
mkdocs serve
- 1
- 在瀏覽器中打開 http://127.0.0.1:8000/ , 你將看到以下頁面:
內建服務器支持在配置文件、文檔目錄或主題發生改變時自動載入並重新生成文檔,編輯 docs/index.md
文件並保存,刷新瀏覽器你將看到文檔被同步更新。現在可以開始編輯配置文件 mkdocs.yml
了,把 site_name
改成其他內容並保存文檔。
- 添加頭部的導航條
curl ‘jaspervdj.be/lorem-markdownum/markdown.txt‘ > docs/about.md
- 1
將這條語句粘貼到命令行,然後回車,你會發現,提示不是內部命令,然後小編用Everything搜索了,然並卵。後來發現,執行完這句話以後,在工程的docs/目錄下創建了about.md文檔。為了測試,我又創建了一個文檔:
curl ‘jaspervdj.be/lorem-markdownum/markdown.txt‘ > docs/development.md
- 1
然後,這個時候,需要在配置文件mkdocs.yml中配置導航條:
site_name: 代高凱的開發文檔
pages:
- Home: index.md
- Develoment: development.md
- About: about.md
- 1
- 2
- 3
- 4
- 5
當Ctrl+s保存後,就會發現網頁變成了:
瞬間就變了,十分高效!!!而且,在這個過程中,不用重啟內置的服務器,也不用刷新界面。
- 主題
在配置文件中添加主題:
theme: readthedocs
- 1
其實我一直覺得這個主題超級醜,不過官方給出的demo是這個,而且我公司暫時也用的這個,不過還是很醜。
- 站點生成
mkdocs build
- 1
該命令創建了一個 site
新目錄,可以到項目文件夾中查看,都被保存在了工程名/sit目錄下。註意源碼被分別輸出為 index.html
和 about/index.html
.主題中的其他文件也被復制到了 site
目錄中。
如果你使用 git
等版本控制系統,,你可能不希望提交構建之後的文檔到版本庫,在 .gitignore
中添加site/
即可忽略該目錄。
一段時間後,可能有文件被從源碼中移除了,但是相關的文檔仍殘留在 site
目錄中。在構建命令中添加--clean
參數即可移除這些文檔。
mkdocs build --clean
- 1
- 發布
MkDocs 生成的文檔只包含靜態文件,因此你可以將文檔部署到任意地方。GitHub project pages 和Amazon S3 是不錯的選擇,只需上傳 site
目錄到你需要發布的位置即可。
- 如果是公司的項目,項目文檔不能對外開放,你可以上傳到公司的GitLab上。
- 如果是個人的項目,你可以上傳到GitHub上。
註意事項
-
如果上傳圖片,目前我所知道的有兩種方式,第一,就是將圖片上傳到某個地方,比如通過markdown來上傳,然後復制過來。。。小編剛開始的時候就是用的這麽菜的方法,沒辦法,為了所見即所得,忍了;
-
後來小編發現如果創建站點的話,將圖片和文檔放在同一個文件夾中即可,或者寫清楚圖片的路徑即可。優點就是,比較方便,缺點就是如果直接復制出來.md文檔,圖片顯示不出來。
-
如果修改了文字,那麽保存的時候會瞬間刷新,如果是圖片的話,有時候需要重啟本地內置的服務器。
本文轉自:http://blog.csdn.net/KevinDGK/article/details/52388542
MkDocs項目文檔生成器