本文选自《了不起的Markdown》，作者：毕小烦

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

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

环境

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

安装

$ pip install mkdocs

查看 mkdocs 版本

$ mkdocs -V
mkdocs, version 0.16.3

或

$ pip show mkdocs
Name: mkdocs
Version: 0.16.3
Summary: Project documentation with Markdown.
Home-page: http://www.mkdocs.org
Author: Tom Christie
Author-email: tom@tomchristie.com
License: BSD
Location: /Library/Python/2.7/site-packages
Requires: tornado, Jinja2, click, Markdown, PyYAML, livereload

查看 mkdocs 帮助

$ mkdocs --help
Usage: 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 bixiaofan
INFO    -  Creating project directory: bixiaofan
INFO    -  Writing config file: bixiaofan/mkdocs.yml
INFO    -  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 layoutmkdocs.yml    # The configuration file.docs/index.md  # The documentation homepage....       # Other markdown pages, images and other files.# 查看配置文件 mkdocs.yml
$ cat mkdocs.yml
site_name: My Docs

启动服务

$ mkdocs serve
INFO    -  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 目录下。

小贴示：

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

发布项目

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

本文选自《了不起的Markdown》，作者：毕小烦

MkDocs 快速入门相关推荐

Shiro第一个程序:官方快速入门程序Qucickstart详解教程
目录一.下载解压二.第一个Shiro程序 1. 导入依赖 2. 配置shiro配置文件 3. Quickstart.java 4. 启动测试三.shiro.ini分析四.Quickstart. ...
计算机入门新人必学,异世修真人怎么玩？新手快速入门必备技巧
异世修真人怎么快速入门?最近新出来的一款文字修仙游戏,很多萌新不知道怎么玩?进小编给大家带来了游戏新手快速入门技巧攻略,希望可以帮到大家. 新手快速入门攻略 1.开局出来往下找婆婆,交互给点钱,旁边有 ...
Spring Boot 2 快速教程：WebFlux 快速入门（二）
2019独角兽企业重金招聘Python工程师标准>>> 摘要: 原创出处 https://www.bysocket.com 「公众号:泥瓦匠BYSocket 」欢迎关注和转载,保留摘 ...
Apache Hive 快速入门 (CentOS 7.3 + Hadoop-2.8 + Hive-2.1.1)
2019独角兽企业重金招聘Python工程师标准>>> 本文节选自<Netkiller Database 手札> 第 63 章 Apache Hive 目录 63.1. ...
《iOS9开发快速入门》——导读
本节书摘来自异步社区<iOS9开发快速入门>一书中的目录,作者刘丽霞 , 邱晓华,更多章节内容可以访问云栖社区"异步社区"公众号查看目录前言第1章 iOS ...
BIML 101 - ETL数据清洗系列 - BIML 快速入门教程 - 序
BIML 101 - BIML 快速入门教程做大数据的项目,最花时间的就是数据清洗. 没有一个相对可靠的数据,数据分析就是无木之舟,无水之源. 如果你已经进了ETL这个坑,而且预算有限,并且有大量的 ...
python scrapy菜鸟教程_scrapy学习笔记（一）快速入门
安装Scrapy Scrapy是一个高级的Python爬虫框架,它不仅包含了爬虫的特性,还可以方便的将爬虫数据保存到csv.json等文件中. 首先我们安装Scrapy. pip install sc ...
OpenStack快速入门
OpenStack云计算快速入门(1) 该教程基于Ubuntu12.04版,它将帮助读者建立起一份OpenStack最小化安装.我是五岳之巅,翻译中多采用意译法,所以个别词与原版有出入,请大家谅解.我 ...
Expression Blend实例中文教程(2) - 界面快速入门
上一篇主要介绍Expression系列产品,另外概述了Blend的强大功能,本篇将用Blend 3创建一个新Silverlight项目,通过创建的过程,对Blend进行快速入门学习. 在开始使用Ble ...

MkDocs 快速入门

快速开始

创建项目

启动服务

添加页面

配置主题

生成站点

发布项目

MkDocs 快速入门相关推荐

最新文章

热门文章