windows上使用mkdocs搭建靜態博客

windows上使用mkdocs搭建靜態博客

以前嘗試過用HEXO搭建靜態博客，最近發現有個叫mkdocs的開源項目也是搭建靜態博客的好選擇，並且它支持markdown格式，下面簡要介紹一下mkdocs的環境搭建過程

項目地址：https://github.com/mkdocs/mkdocs

介紹：英文版----http://www.mkdocs.org/

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

使用環境：win8.1  64位

基本配置

首先，經過pip安裝mkdocs

MkDocs 支持 Python 2.6, 2.7, 3.3 和 3.4

pip  install mkdocs

安裝後查看一下版本：

mkdocs  --version

添加路徑

找到mkdocs.exe，把它的路徑添加到環境變量中

在任意位置上新建一個項目文件夾，好比名爲myproject

mkdocs  new  myproject

cd  myproject

項目文件夾下的文件以下：

mkdocs.yml是配置文件,docs文件夾下的名爲index.md的文件，當你啓動服務的時候就會顯示這個md文件的內容。（感受這個項目文件夾比hexo的簡單多了）

mkdocs包含了一個內建服務器能夠用來預覽當前文檔。將當前路徑切換到myproject下，輸入mkdocs  serve啓動服務

瀏覽器中輸入http://127.0.0.1:8000/並打開

顯示：

經常使用的命令：

mkdocs  new  dirname ：建立項目

mkdocs   serve：開啓服務

mkdocs   build：構建文件的站點

mkdocs  help：查看幫助

若是須要自定義上圖的頁面，能夠修改mkdocs.yml的配置，其實mkdocs.yml的原始內容很少，也就一行：

site_name: My Docs

能夠將My Docs修改爲你想要的內容，而後重啓服務後上圖的My Docs就會變成你輸入的內容了

添加頁面

首先，執行下面

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

 

可是cmd上提示curl是無效的命令，額。。。先下載curl

點擊下面的連接：

https://curl.haxx.se/download.html

找到win64的而且後綴爲CAB的選項下載，解壓

找到AMD64文件夾下，將curl.exe的路徑添加到環境變量

cmd上切換到AMD64目錄，試試curl --help，若是有正常的回覆那麼就安裝完成了

執行前面原來失敗的步驟，再加個：

curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > \mkdocs\myproject\docs\more.md

執行完畢後在docs目錄下顯示了新生成的md文件

若是須要爲文檔添加導航條，只要在配置文件中添加須要的標題和排序：

site_name: My Docs

pages:

- [index.md, Home]

- [about.md, About]

- [more.md,More]

theme: readthedocs

刷新瀏覽器便可看到 Home 和 About 還有More導航欄目

固然，你也能夠切換主題，這裏我用到的是ReadTheDocs 主題

生成站點

cmd下輸入：

mkdocs build

此時會生成一個名爲site的目錄

注意源碼被分別輸出爲 index.html 和 about/index.html. 主題中的其餘文件也被複制到了 site 目錄中.

若是你使用 git 等版本控制系統, 你可能不但願提交構建以後的文檔到版本庫. 在 .gitignore 中添加 site/ 便可忽略該目錄.

 echo "site/" >> .gitignore 

若是你使用其餘版本控制系統則須要查閱相關文檔以肯定如何忽略指定目錄.

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

 mkdocs build –clean

發佈

能夠發佈到github.page，新建一個github的項目並在setting上作好相關設置就能夠了

須要深刻研究的話能夠看前面放出的連接

Jekyll 是一個靜態網站生成器，和mkdocs一塊兒協同工做能夠搭建一個很好的博客

能夠參考：http://www.ruanyifeng.com/blog/2012/08/blogging_with_jekyll.html