搭建mkdocs静态页面实践

悠悠 2023-06-11 04:27 10阅读 0赞

## 一、背景和介绍 ##

*  背景简单说下，需要一个静态页面来呈现说明某些文档，浏览器可以直接访问，接入成本要低
 *  这里主要介绍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][https_github.com_squidfunk_mkdocs-material]，粘贴到自己新建工程的根路径下，如图所示即可![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2h1b2RvdWJp_size_16_color_FFFFFF_t_70][] 代码上传到git上（可以是github，也可以是自己搭建的git远程仓库，也可以是公司的git私有远程仓库，看个人需求）；当然之前如果有mkdocs的模版，也可复制之前的模版，都弄完后，项目工程路径结构如下：![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2h1b2RvdWJp_size_16_color_FFFFFF_t_70 1][]
    
     *  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 xx@xxx.com
                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分钟轮训一次
         *  ![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2h1b2RvdWJp_size_16_color_FFFFFF_t_70 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上，就可以自动更新服务器上的静态文件了
     *  注：写的是大体思路，没有细致到每个环节，可能不同情况需要微调某些步骤或脚本，自己控制就好

[https_github.com_squidfunk_mkdocs-material]: https://github.com/squidfunk/mkdocs-material
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2h1b2RvdWJp_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/2019102913543934.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2h1b2RvdWJp,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2h1b2RvdWJp_size_16_color_FFFFFF_t_70 1]: /images/20230531/5363d769e9ec471cb3e031e5d6f5c025.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2h1b2RvdWJp_size_16_color_FFFFFF_t_70 2]: /images/20230531/5f779a3ac16d494790625322ee018adb.png