之前把学习笔记用sphinx生成然后托管在github上,然后用readthedocswebhook自动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

first_mkdocs

所有命令

#生成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的库项目,另一种则是创建任意库项目可以在settingLaunch 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 master

username库项目毫无疑问地址就是username.github.io,任意库项项目生成的工程页则是username.github.io/projectname.
我现在的做法是在username库项目下的CNAME指向我的主域名farwmarth.com,learndocs库项项目CNAME指向我的二级域名learndocs.farwmarth.com.

dnspod配置如下:

mkdocscname

最后learndocs库项项目源文件托管到master分支,然后mkdocs gh-deploy把生成的html静态页面托管是gh-pages分支。注意master分支把生成的site目录忽略掉

echo "site/" >> .gitignore