之前把学习笔记用 sphinx 生成然后托管在 github 上,然后用 readthedocs 的 webhook 自动 build 文章数量渐多感觉排版拥挤.于是google了一下找了个替代品,那就就是这篇文章的主角 mkdocs
简介mkdocs 是一个支持 markdown 语法的项目文档管理工具，结构很简单,一个 yml 配置文件管理文档结构和主题信息, docs 目录则是项目文档.官方文档( http://www.mkdocs.org/ )
新建工程 #安装mkdocs pip install mkdocs #新建工程目录 mkdocs new my-project #切换到工程目录 cd my-project工程目录如下:
├── mkdocs.yml ├── docs │ ├── index.md 启动 #启动服务器,默认端口是8000 Running at: http://127.0.0.1:8000/ mkdocs serve
所有命令 #生成html mkdocs build #新建工程目录 mkdocs new my-project #部署到github的gh-deploy分支 mkdocs gh-deploy -v #markdown生成json文件 mkdocs json #启动预览 mkdocs serve 配置
我用的主题是 material :
pip install mkdocs-material项目配置大概列了一,大致分为几部分： 项目信息 ， 托管信息 ， 版权信息 ， 主题与文档目录 ， 配色信息 , 额外插件 ，还有就是 项目文档目录结构 有些配置与主题相关
# Project information site_name: farwmarth’s note site_author: 'farwmarth' site_url: 'http://learndocs.farwmarth.com' # Repository # repo_name: 'GitHub' # repo_url: 'https://github.com/wujiyu115/learndocs' # Copyright copyright: 'Copyright (c) 2016 farwmarth' # Documentation and theme docs_dir: 'docs' theme: 'material' # theme: 'cinder' extra: palette: primary: 'blue grey' accent: 'blue grey' author: github: 'wujiyu115' # Extensions markdown_extensions: #高亮 - codehilite(css_class=code) - admonition - toc: permalink: '#' pages: - Home: 'index.md' - 数据结构与算法: - '排序算法介绍':'data_algorithms/algorithms1_intro.md' - c++基础: - 'c++环境搭建(Win)':'cplus/cplus_win.md' - '编译过程':'cplus/cplus4_complier.md' - '常量修饰符':'cplus/cplus5_const.md' - python: - '语言简介':'python/py1_intro.md' 托管到github之前误认为 github 只能有一个 page 页,看了 官方 的介绍之后发现并非如此，有两种方式创建 page 页，一种是创建一个就 {username}.github.com 的库项目,另一种则是创建任意库项目可以在 setting 中 Launch automatic page generator 生成 gh-pages 分支，创建方式这里就不细说了,可以根据 page官方 的引导去操作。
这个表格是 username库项目 和 任意库项项目 对应的域名指向.
Type of GitHub Pages site Pages default domain & host location on GitHub Location of the source files for building your Pages site User Pages site username.github.io master Project Pages site owned by a user account 、 master , gh-pages , or a /docs folder on masterusername库项目 毫无疑问地址就是 username.github.io , 任意库项项目 生成的工程页则是 username.github.io/projectname .
我现在的做法是在 username库项目 下的 CNAME 指向我的主域名 farwmarth.com , learndocs库项项目 的 CNAME 指向我的二级域名 learndocs.farwmarth.com .
dnspod 配置如下：
最后 learndocs库项项目 源文件托管到 master 分支,然后 mkdocs gh-deploy 把生成的 html 静态页面托管是 gh-pages 分支。注意 master 分支把生成的 site 目录忽略掉
echo "site/" >> .gitignore