Mkdocs在html網頁上看markdown
1. 本文目的
介紹一下目前發布在線文檔的時候，如何寫出的文檔更加的高效簡潔，讓人賞心悅目的同時，又能學到東西。這就需要利用markdown進行文檔的整理，一般來說，如果排版不好看的文檔，讓人看下去的欲望都沒有，更何況涉及到專業領域的知識時，更加沒有讓人閱讀的想法。我想一個人不管技術水平如何，文檔一定要整理好，技術水平是能力問題，文檔整理是習慣問題。所以堅持寫出好文檔，這才是我需要思考和不斷努力的事情。
2. Mkdocs介紹
Mkdocs是什么？一句話概括如下
MkDocs 是一個用於創建項目文檔的 快速, 簡單 , 完美華麗 的靜態站點生成器. 文檔源碼使用 Markdown 來撰寫, 用一個 YAML 文件作為配置文檔.
具體可以查mkdocs的官網
https://www.mkdocs.org/
其界面如下圖所示
也可以查看Mkdocs的配置文檔。
https://markdown-docs-zh.readthedocs.io/zh_CN/latest/
以上介紹的都很詳細了，紙上得來終覺淺，絕知此事要恭行。下面來詳細介紹一下基本的情況
3. DEMO的演示
3.1 配置需求
安裝平台ubuntu16.04
$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2
3.2 安裝mkdocs
pip install mkdocs
3.3 新建工程
在這里，我們新建一個mkdocs的工程
mkdocs new my-project
cd my-project
3.4 啟動服務器
可以快速開始體驗
mkdocs serve
啟動服務器自動的地址
如果想自定義一個地址
可以輸入下面的地址
mkdocs serve --dev-addr=192.168.31.199:1666
或者
mkdocs serve -a 127.0.0.1:9999
3.5 查看demo
配置完成后，就可以啟動了
4. 添加頁面
MkDocs 中一個 Markdown 文檔渲染后就是一個頁面，因此如果我們想添加一個頁面，就需要先在 docs 目錄下添加一個 Markdown 文件，文件的后綴名可以是 md、markdown 、mdown、 mkdn 、mkd。
4.1 在目錄結構中添加一個新的界面
在docs目錄中添加test.md文檔，並且項目查看的結構
# 查看項目結構
$ tree
.
├── docs
│ ├── index.md
│ └── test.md
└── mkdocs.yml
4.2 修改配置文件mkdocs.yml
site_name: 博客系統
pages:
- 首頁: index.md
- 測試: test.md
4.3 添加頭部導航欄
curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/development.md
4.4 換主題
theme: mkdocs 默認
theme: readthedocs
下面進行mkdocs主題切換
site_name: 測試博客
page:
- Home: index.md
- Develoment: development.md
- About: about.md
theme: mkdocs
主題分為內置主題、第三方主題和自定義主題，內置主題如上所述，直接配置主題名就可以了；如果是第三方主題，就需要先安裝主題再進行配置了；自定義主題有點難度本文暫不介紹。
4.5 生成站點
如果要將項目發布到網站上，則需要生成靜態站點
mkdocs build
- 使用 mkdocs build –clean 可以在構建時清理一些殘留資源。
- site 需要部署到 webserver 上才能正常運行。
發布的文檔可以部署到任意的地方其中GitHub project pages 和Amazon S3 是不錯的選擇。
5. 總結
對於項目的發布來說，需要構建文檔，所以文檔的建設十分的重要。一定要整理好文檔，好記性不如爛筆頭，只有多做記錄和多些總結，才能進步成長。