mkdocs-material符合google material ui规范的静态文档网站生成器，使用markdown进行文档书写

mkdocs 介绍

MkDocs是一个快速、简单、华丽的静态网站生成器，适用于构建项目文档。文档源文件以Markdown编写，并使用一个YAML文件来进行配置。

  • python编写的markdown解释器、编译器，带有本地cli工具
  • 自带基于Tornado的小型http服务，用于本地调试
  • 内置一键式发布至GitHub Pages
  • 内置mkdocs风格、readthedocs风格的主题，并支持自定义主题
  • 支持调用python模块实现语法及渲染的扩展

mkdocs-material 介绍

  • python模块，符合google material ui规范的mkdocs自定义主题
  • 针对特定语法、功能做了渲染优化
  • 根据客户端浏览器页面尺寸自动缩放，对PC、移动设备都友好
  • 丰富的页面配色，多达19种主体配色和16种悬停链接文字配色
  • 支持中文搜索
  • 支持统计功能，如百度统计，谷歌统计

安装mkdocs

1

pip install mkdocs

MkDocs支持Python2.7.9+、3.4、3.5、3.6、3.7和pypy。

若下载慢，可更换安装源为豆瓣

1

pip install --trusted-host pypi.douban.com -i http://pypi.douban.com/simple/ mkdocs

创建项目

1
2

mkdocs new my-project
cd my-project

运行项目

通过运行mkdocs serve命令启动服务器

1
2

cd my-project
mkdocs serve

在浏览器中打开http://127.0.0.1:8000/

下载主题

1

pip install mkdocs-material

若下载慢，可更换安装源为豆瓣

1

pip install --trusted-host pypi.douban.com -i http://pypi.douban.com/simple/ mkdocs-material

在mkdocs.yml中修改主题

1
2

theme:
  name: material

选择下载其它主题

1

pip install mkdocs-windmill

发布到GitHub pages

在github仓库点击Settings，然后设置Pages服务的目标分支为gh-pages

通过mkdocs gh-deploy自动编译出html(site目录下),并发布到仓库的gh-pages分支上，GitHub pages会自动从gh-pages分支部署服务。

发布到个人HTTP Server

通过mkdocs build编译出html并手动同步至http server的根目录

添加页面

在my-project/docs/里放置.md文件

1

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

然后在mkdocs.yml里添加

1
2
3
4
5

site_name: MkLorum
site_url: https://example.com/
nav:
    - Home: index.md
    - About: about.md

参考