MkDocs-服务搭建和使用

MkDocs 官方文档

介绍

MkDocs 是用于快速创建项目文档的静态网站生成器. 其使用 Markdown 编写文档, 支持用 YAML 进行简单的配置和主题定制.

安装

可直接用 pip 装:

pip install mkdocs

查看是否安装成功:

mkdocs --version

创建项目文档目录

mkdocs new <project-name>

如:

mkdocs new hello

会在当前目录下创建 hello 目录, 目录结构为:

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

其中:

• mkdocs.yml 是配置文件
• docs 目录存放文档, 默认下面有 index.md 作为默认显示文档

启动 Web 服务

先进到项目目录:

cd hello
mkdocs serve

之后在浏览器访问 http://127.0.0.1"8000

(这里显示的就是 index.md 的内容)

显示的文档能热加载, 即如果内容改变, Web 页面也会更新.

可以在 mkdocs.yml 中修改 site_name 字段来更改浏览器中 Tab 显示的文本, 如:

site_name: Hello

添加页面

其实就是在 docs/ 目录下添加文件:

curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

默认情况下, 文件的一级标题显示在 Nav 栏:

也可以在 mkdocs.yml 配置文件中更改 Nav 栏显示的顺序以及内容:

site_name: Hello
nav:
  - Home: index.md
  - About: about.md

(也就是修改 nav 字段)

效果如下:

也可以嵌套设置, nav 的配置如:

site_name: Hello
nav:
  - Home: index.md
  - About: about.md
  - Test:
    - Hello: hello.md

效果如;

(这里换了主题了)

也可以嵌套目录, 如 docs/test/hello.md, 此时 nav 中引用如:

site_name: Hello
nav:
  - Home: index.md
  - About: about.md
  - Test:
    - Hello: hello.md
    - World: test/hello.md
theme: readthedocs

设置页面的 Meta-Data

如:

---
title: My Document
summary: A brief description of my document.
authors:
    - Waylan Limberg
    - Tom Christie
date: 2018-07-10
some_url: https://example.com
---
This is the first paragraph of the document.

这些主要是生成的 HTML 中有用, 并没有在页面中显示出.

更换主题

修改 mkdocs.yml 文件中的 theme 字段即可, 默认是 mkdocs, 这里修改成 readthedocs 如:

site_name: hello
nav:
  - Home: index.md
  - About: about.md
theme: readthedocs

则效果如:

可以在 theme 字段下进一步配置. (具体看文档, 这里尝试的时候出了点问题, 没啥效果)

还有许多第三方主题, 可以在 the ranked catalog 查看.

material 主题

安装:

pip install mkdocs-material

配置:

theme:
  name: material

效果如:

自定义主题

若只是对当前主题做一些小修改, 可以自己编写一些 css 或 js 来添加样式.

比如, 在 docs/ 目录下创建 style.css 文件, 内容为:

h1 {
    color: red;
}

然后再 mkdocs.yml 文件中添加:

extra_css:
  - style.css

(前提是没启用主题似乎是)

若要添加 js 则配置 extra_js.

效果如:

若要自己完全写一个主题, 细节见 官网.

更改 Tab 栏中的图标

需要在 docs/ 目录下创建 img 子目录, 然后把 favicon.ico 文件放进去即可:

cd docs
mkdir img
cp /path/to/your/favicon favicon.ico

效果如:

构建静态文件

可以用:

mkdocs build

在 site/ 目录下生成静态文件, 可以用 Web 代理服务器代理页面.

$ ls site
about  fonts  index.html  license  search.html
css    img    js          mkdocs   sitemap.xml

Internal Links

也就是在 docs 下的文件间跳转, 如:

Please see the [project license](license.md) for further details.

(细节见 官方文档)

配置细节

见 官网.

插件编写

见 官网.