Mkdocs在html網頁上看markdown

目錄

• Mkdocs在html網頁上看markdown
  • 1. 本文目的
  • 2. Mkdocs介紹
  • 3. DEMO的演示
    • 3.1 配置需求
    • 3.2 安裝mkdocs
    • 3.3 新建工程
    • 3.4 啓動服務器
    • 3.5 查看demo
  • 4. 添加頁面
    • 4.1 在目錄結構中添加一個新的界面
    • 4.2 修改配置文件mkdocs.yml
    • 4.3 添加頭部導航欄
    • 4.4 換主題
    • 4.5 生成站點
  • 5. 總結

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

1. 使用 mkdocs build –clean 能夠在構建時清理一些殘留資源。
2. site 須要部署到 webserver 上才能正常運行。

發佈的文檔能夠部署到任意的地方其中GitHub project pages 和Amazon S3 是不錯的選擇。

5. 總結

對於項目的發佈來講，須要構建文檔，因此文檔的建設十分的重要。必定要整理好文檔，好記性不如爛筆頭，只有多作記錄和多些總結，才能進步成長。