搭建mkdocs静态页面实践

一、背景和介绍

• 背景简单说下，需要一个静态页面来呈现说明某些文档，浏览器可以直接访问，接入成本要低
• 这里主要介绍mkdocs，mkdocs接入成本低，语法简单

二、准备

• git：用于托管文档代码，版本迭代方便
• docker：用于快速构建mkdocs环境依赖
• jenkins：用于SCM自动同步代码到静态页面
• 注：
  • 如果不用docker也可以，可以单独配置mkdocs的依赖环境，主要依赖python3，pip，mkdocs包（建议使用mkdocs-materia主题，比较好看，当然你也可以选用别的主题）
  • 如果不实用jenkins实现自动同步代码，也可以使用git hook来实现，本文不做深入介绍

三、搭建步骤

• 本地安装下mkdocs的依赖，先安装python3，再执行pip install mkdocs，pip install mkdocs-material即可
• idea或其他编译器创建工程，mkdocs xxx执行后即可创建出一个基础的mkdocs工程，稍加修改，添加本地material模版文件（用于自定义使用，可以对前端代码稍作修改，比如不想展示模版中的某个icon，想修改原模版某个控件的长宽比例等等，修改需要基本的js和html技术基础），模版文件可以从github下下载，https://github.c