MkDocs 快速入门

本文选自《Markdown 实用指南》 作者：毕小烦

MkDocs 是一个用 Python 开发的静态站点生成器工具，它可以非常简单快速的创建项目文档。MkDocs 的文档源码使用 Markdown 编写，配置文件使用 YAML 编写，可以一键编译成静态站点。

很多开源的项目文档都使用 MkDocs 编写，因此我们非常有必要学习一下。

环境

• 支持 macOS/Linux/Windows
• 安装 Python: 2.7.8 +

安装

$ pip install mkdocs

查看 mkdocs 版本

$ mkdocs -Vmkdocs, version 0.16.3

或

$ pip show mkdocsName: mkdocsVersion: 0.16.3Summary: Project documentation with Markdown.Home-page: http://www.mkdocs.orgAuthor: Tom ChristieAuthor-email: [e-mail]: BSDLocation: /Library/Python/2.7/site-packagesRequires: tornado, Jinja2, click, Markdown, PyYAML, livereload

查看 mkdocs 帮助

$ mkdocs --helpUsage: mkdocs [OPTIONS] COMMAND [ARGS]...  MkDocs - Project documentation with Markdown.Options:  -V, --version  Show the version and exit.  -q, --quiet    Silence warnings  -v, --verbose  Enable verbose output  -h, --help     Show this message and exit.Commands:  build      Build the MkDocs documentation(构建 MkDocs 文档)  gh-deploy  Deploy your documentation to GitHub Pages(把文档部署到 Github Pages)  json       Build the MkDocs documentation to JSON files...(把 MkDocs 文档构建成 JSON 文件)  new        Create a new MkDocs project(创建一个新的项目)  serve      Run the builtin development server(启动一个内置的开发服务)

升级

$ pip install -U mkdocs

卸载

$ pip uninstall mkdocs

快速开始

创建项目

# STEP 1.创建一个新的 MkDocs 项目$ mkdocs new bixiaofanINFO    -  Creating project directory: bixiaofanINFO    -  Writing config file: bixiaofan/mkdocs.ymlINFO    -  Writing initial docs: bixiaofan/docs/index.md# STEP 2. 切换到项目中$ cd bixiaofan/# STEP 3. 查看项目结构$ tree.├── docs  # mardown 源码放到 docs 中│   └── index.md└── mkdocs.yml # 配置文件1 directory, 2 files# 查看 docs/index.md，index.md 是默认的首页$ cat docs/index.md# Welcome to MkDocsFor full documentation visit [mkdocs.org](http://mkdocs.org).## Commands* `mkdocs new [dir-name]` - Create a new project.* `mkdocs serve` - Start the live-reloading docs server.* `mkdocs build` - Build the documentation site.* `mkdocs help` - Print this help message.## Project layout    mkdocs.yml    # The configuration file.    docs/        index.md  # The documentation homepage.        ...       # Other markdown pages, images and other files.# 查看配置文件 mkdocs.yml$ cat mkdocs.ymlsite_name: My Docs

启动服务

$ mkdocs serveINFO    -  Building documentation...INFO    -  Cleaning site directory[I 170923 08:07:03 server:283] Serving on http://127.0.0.1:8000[I 170923 08:07:03 handlers:60] Start watching changes[I 170923 08:07:03 handlers:62] Start detecting changes[I 170923 08:07:13 handlers:133] Browser Connected: http://127.0.0.1:8000/

在浏览器中打开 http://127.0.0.1:8000 ，启动效果如下图所示：

服务器启动后，当配置文件、文档目录或主题发生改变时，服务器就会自动加载变更并生成新的文档。

小贴示：

服务器默认地址为 127.0.0.1:8000 ，如果端口被占用怎么办呢？

当然也支持自定义地址，使用下面这命令：

mkdocs serve –dev-addr=127.0.0.1:8888

或

mkdocs serve -a 127.0.0.1:9999

添加页面

MkDocs 中一个 Markdown 文档渲染后就是一个页面，因此如果我们想添加一个页面，就需要先在 docs 目录下添加一个 Markdown 文件，文件的后缀名可以是 md、markdown 、mdown、 mkdn 、mkd。

实例演示：

STEP 1. 在 docs 目录中添加 test.md

# 查看项目结构$ tree.├── docs│   ├── index.md│   └── test.md└── mkdocs.yml

说明：

docs 的目录结构对应着生成页面的 URL，本例中对应的 URL 是：

http://127.0.0.1:8000/http://127.0.0.1:8000/test/

STEP 2. 修改配置文件 mkdocs.yml

site_name: Markdown实用指南pages:- 首页: index.md- 测试: test.md

说明：

• index.md 是默认的首页
• test.md 是新增页面

效果如下图所示：

小贴示：

文件名暂不支持中文，文件路径中也不要有中文。

配置主题

MkDocs 的主题是可以配置的，默认主题是 mkdocs。

前面的例子中 mkdocs.yml 文件也可以配置成这样：

site_name: Markdown实用指南pages:- 首页: index.md- 测试: test.mdtheme: mkdocs

如果想切换成别的主题，只要更改 theme 的值就可了。

如：

site_name: Markdown实用指南pages:- 首页: index.md- 测试: test.mdtheme: readthedocs

效果如下图所示：

主题分为内置主题、第三方主题和自定义主题，内置主题如上所述，直接配置主题名就可以了；如果是第三方主题，就需要先安装主题再进行配置了；自定义主题有点难度本文暂不介绍。

生成站点

如果想发布项目，需要先构建项目，生成一个静态资源站点。

$ mkdocs build

构建完成后的项目结构如下：

$ tree.├── docs│   ├── index.md│   └── test.md├── mkdocs.yml└── site  # 构建后生成的目录    ├── css    │   ├── highlight.css    │   ├── theme.css    │   └── theme_extra.css    ├── fonts    │   ├── fontawesome-webfont.eot    │   ├── fontawesome-webfont.svg    │   ├── fontawesome-webfont.ttf    │   └── fontawesome-webfont.woff    ├── img    │   └── favicon.ico    ├── index.html    ├── js    │   ├── highlight.pack.js    │   ├── jquery-2.1.1.min.js    │   ├── modernizr-2.8.3.min.js    │   └── theme.js    ├── mkdocs    │   ├── js    │   │   ├── lunr.min.js    │   │   ├── mustache.min.js    │   │   ├── require.js    │   │   ├── search-results-template.mustache    │   │   ├── search.js    │   │   └── text.js    │   └── search_index.json    ├── search.html    ├── sitemap.xml    └── test        └── index.html

构建完成后的资源全部放到了 site 目录下。

小贴示：

1. 使用 mkdocs build –clean 可以在构建时清理一些残留资源。
2. site 需要部署到 webserver 上才能正常运行。

发布项目

site 目录就是我们要发布的项目，我们可以把 site 部署到任意的地方，如： GitHub project pages。

更多请查看《Markdown 实用指南》 作者：毕小烦