文档神器mkdocs

简介

官网:mkdoc.org

mkdocs 基于Python，迅速生成基于Markdown和Yaml配置文件生成web版的文档。

安装

前提是安装了Python和最新版的pip

$ pip install mkdocs

使用

$ mkdocs new any-project
$ cd any-project

此刻，any-project目录中有如下文件

$ tree
$ .
$ ├── docs
$ │   └── index.md
$ └── mkdocs.yml

mkdocs.yaml为配置文件，index.md为文档文件。

# mkdocs.yaml
site_name: any-project
pages:
    - Home: index.md
    - About: about.md
theme: readthedocs

静态页面输出

$ mkdocs build

主题切换

官方除了默认主题还有以下主题可以选择

$ pip install mkdocs-bootstrap
$ pip install mkdocs-bootswatch

• readthedocs 非常geek范的文档主题
• bootstrap Twitter家出品
• bootswatch 这是一个系列，具体如下
  • amelia 红绿主题，丑掉渣
    
    
  • cerulean 浅蓝白组合，淡雅
    
    
  • cosmo 太空主题，黑色导航栏白色背景
    
    
  • cyborg 机械人主题，暗黑系
    
    
  • flatly
    
    
  • journal
    
    
  • readable
    
    
  • simplex
    
    
  • slate
    
    
  • spacelab
    
    
  • united
    
    
  • yeti