MkDocs 使用 Markdown 管理项目文档

坚持写博客也两年多了，使用 hexo 的一个很大的问题就是不太方便写系列性的文章，属于比较随性的想起什么写什么，最近发现了 mkdocs，同样的使用 Markdown 格式编写文档，写系列文章很合适。

• 安装使用
• 配置

它的官网就是用 mkdocs 搭建的。

如果这个界面不熟悉的话，看下面的截图

这是它为著名的 readthedocs 提供的主题，是不是很亲切。

mkdocs 使用配置起来都很简单，它是由 Python 编写的，这是让我亲切的另一个原因。

安装使用

安装

$ pip install mkdocs

生成项目

$ mkdocs new my-project
$ cd my-project

项目的结构如下

启动服务

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes

mkdocs 会启动一个端口为 8000 的服务，效果如下

网页首页默认打开的是文档 docs/index.md，修改文档内容，网页会自动刷新到最新状态。

生成静态文件

$ mkdocs build

随后根目录下会生成一个 site 文件夹，内容是文档的静态网页，使用 Nginx 代理即可访问。

配置

mkdocs 的全部配置都在 mkdocs.yml 中，一个最简单的配置如下

site_name: MkLorum      # 站点名称
nav:                    # 文档目录
    - Home: index.md
    - About: about.md
theme: readthedocs      # 主题

另外还有一些常用配置

• repo_url 页面会生成一个链接，指向仓库地址，可以是 GitHub, Bitbucket, GitLab 等
• site_description 网站的描述
• copyright 版权信息
• google_analytics 配置 Google analytics 信息，接收一个数组

google_analytics: ['UA-36723568-3', 'mkdocs.org']

• docs_dir 文档的存放目录，默认为 docs
• site_dir 生成静态网页的存放目录，默认为 site
• dev_addr 使用 mkdocs serve 时启动的地址和端口号，默认 127.0.0.1:8000

更多的配置详见文档

最近更新

Alfred Workflow 命令行帮助工具

最近热读

Go 判断数组中是否包含某个 item

Vim 高级功能 vimgrep 全局搜索文件

办理北京工作居住证的一些细节

Go 语法错误：Non-declaration statement outside function body

Mac 电脑查看字体文件位置

扫码关注公众号，或搜索公众号“温欣爸比” 及时获取我的最新文章

赏

谢谢你请我喝咖啡

支付宝

微信