本地构建指南

本文档包含mkdocs-material入门基础知识，包括安装、新增文档页面、运行。

基础环境

python: 3.7.2

安装

pip install mkdocs mkdocs-material

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

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

准备项目

• 下载项目

  git clone https://gitlab.zhixueyun.com/document/developer.git
  

  初始化项目

  如果是个人学习，搭建自己的文档站点，使用下列命令初始化一个文档项目

  mkdocs new my-project
  

  该命令会生成my-project目录，进入该目录会看到初始化生成的项目目录结构

添加页面

1. 在项目 docs 目录添加相应的 markdown 文件
2. 按照实际情况在mkdocs.yml配置文件中添加导航，最多支持三级，导航地址为基于 docs目录的地址

   nav:
     - 首页: index.md
     - 一级导航:
       - 二级目录:
         - 三级目录: 文档地址(基于 docs 目录的地址)
   

运行与构建

• 运行

  # 在项目根目录里执行
  mkdocs serve
  

  通过浏览器访问http://127.0.0.1:8000/查看效果

• 构建静态文件

  # 在项目根目录里执行
  mkdocs build
  

  命令执行完毕后可以在项目根目录下看到site目录，这就是文档站点的静态文件，打开index.html即可访问