搭建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.com/squidfunk/mkdocs-material，粘贴到自己新建工程的根路径下，如图所示即可 代码上传到git上（可以是github，也可以是自己搭建的git远程仓库，也可以是公司的git私有远程仓库，看个人需求）；当然之前如果有mkdocs的模版，也可复制之前的模版，都弄完后，项目工程路径结构如下：
  • material模版文件如果本地配置，需要在mkdocs.yml中指定本地路径

    # Project information
    site_name: 'xxx'
    site_author: 'xxx'
    docs_dir: docs
    nav:
      - 首页: 'index.md'
      - 自媒体测试工具:
        - UI自动化图片对比: 'wemedia/ui_compare.md'
        - Mock热替换: 'wemedia/mock_hot_update.md'
    
    
    # Repository
    #repo_name: 'squidfunk/mkdocs-material'
    #repo_url: 'https://github.com/squidfunk/mkdocs-material'
    
    ## Copyright
    copyright: 'Copyright © xxx'
    
    # Configuration
    theme:
      name: 'material'
      custom_dir: 'material'###这里可以需要指定本地模版文件路径，如果不配置，则直接拉取安装的默认material模版
      language: 'zh'
      palette:
        primary: 'teal'
        accent: 'blue'
      font:
        text: 'Bree'
        code: 'Bree Serif'
      feature:
        tabs: false

    执行mkdocs serve启动mkdocs服务，就可以在浏览上访问静态文档页面了，至此，成功了一半了

• 准备docker 镜像（需要自行安装docker，比较简单，自行百度即可）
  • docker相关
    • 制作Dockerfile

      FROM squidfunk/mkdocs-material
      MAINTAINER [email protected]
      WORKDIR /docs
      ADD doc.tar.gz /docs

       

    • 进入服务器或测试机器，执行以下命令，mkdir -p /home/worker/docs && cd /home/worker/docs && docker pull squidfunk/mkdocs-material && docker build -t xxx-mkdocs . && docker run -d -p 9998:8000 xxx-mkdocs"，服务器上的mkdocs就以docker形式启动起来了，访问http://服务器ip:9998即可访问到静态页面了

    • 至此，成功了90%了，还剩最后一步，结合jenkins，实现更新mkdocs代码自动部署到服务器上，实现实时更新静态mkdocs文档

• 创建jenkins job（当然如果你使用的gitlab托管mkdocs代码，你可以使用gitlab的pipeline来替代jenkins，更简单；如果你熟悉git的hook使用方式，也可以替代jenkins，也比较简单，看你自己熟悉哪一种方式）

  • 新建jenkins job，说下关键地方的配置

    • 构建方式选择定时轮训仓库代码变化，频率建议1或2分钟轮训一次

    • 

    • 将上一步的shell脚本添加到job的build的shell脚本中，这里设计公司内部地址，不粘贴了，大概命令如下

      #找到你之前定义的Dockerfile，至于放在哪，你自己决定，构建脚本中拉取到Dockerfile就行，我直接把Dockerfile放到了git代码上，和mkdocs的代码在一起托管，获取Dockerfile的脚本，自己写一下对应的shell脚本吧
      #ci部署脚本中还需要检查之前是否已经部署了相同的docker镜像，如果有，需要删掉原来的容器和镜像，删除后再部署镜像
      cmd="docker ps -a|grep xxx|wc -l"
      RESPONSE=`ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 worker@测试机器ip "$cmd"`
      ret=$?
      
      if [ "$RESPONSE" != '0' ]; then
          cmd="docker ps -a| grep xxx |awk '{print \$1}'| xargs docker rm -f"
          RESPONSE=`ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 worker@${host} "$cmd"`
          echo $?
      fi
      
      cmd="docker ps |grep xxx|wc -l"
      RESPONSE=`ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 worker@测试机器ip "$cmd"`
      ret=$?
      
      if [ "$RESPONSE" != '0' ]; then
          cmd="docker ps | grep xxx |awk '{print \$1}'| xargs docker stop"
          RESPONSE=`ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 worker@测试机器ip "$cmd"`
          echo $?
      fi
      
      
      #如果涉及到jenkins的slave机器与实际配置mkdocs的机器不是同一个机器，需要ssh命令，可参考如下命令
      cmd="mkdir -p /home/worker/docs && cd /home/worker/docs && docker pull squidfunk/mkdocs-material && docker build -t xxx-mkdocs . && docker run -d -p 9998:8000 xxx-mkdocs"
      RESPONSE=`ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 worker@测试机器ip 
       "$cmd"`

      至此，配置完成了，之后你每次更新mkdocs的代码，然后push到git上，就可以自动更新服务器上的静态文件了

  • 注：写的是大体思路，没有细致到每个环节，可能不同情况需要微调某些步骤或脚本，自己控制就好