mkdocs自动化部署知识库

了解过Traefik,nginx-ingress的同学都知道他们的官方文档都是基于mkdocs和material主题制作而成，你觉得这种文档库怎么样？有没有心动把自己的文档也整成那样的？，下面我们直接动手干起来吧。

配置pip国内的下载源

☸️  devcluster🔥 kube-ops  ~  🐳 👉 cat ./.pip/pip.conf
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

安装mkdocs

☸️  devcluster🔥 kube-ops  ~  🐳 👉 pip3 install mkdocs
Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
Requirement already satisfied: mkdocs in /Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages (1.1.2)
...
WARNING: You are using pip version 19.2.3, however version 20.1.1 is available.
You should consider upgrading via the 'pip install --upgrade pip' command.

创建并运行一个新的文档库

☸️  devcluster🔥 kube-ops  ~  🐳 👉 mkdocs new cloudnativecosystem
☸️  devcluster🔥 kube-ops  ~  🐳 👉 cd cloudnativecosystem
☸️  devcluster🔥 kube-ops  ~/cloudnativecosystem  🐳 👉 ls
docs       mkdocs.yml

创建一个新的GIT仓库https://github.com/linuxermaster/cloudnativecosystem_mkdocs

配置通过SSH无密访问代码仓库

ssh-keygen -t rsa -C "email@qq.com"

然后将公钥拷贝到GITHUB的SSH-KEY中

测试本地是否可以远程连接

# ssh -T git@github.com
Hi linuxermaster! You've successfully authenticated, but GitHub does not provide shell access.

然后需要在cloudnativecosystem目录内初始化.git仓库，然后添加远程仓库地址

cd cloudnativecosystem
git init
git remote add origin https://github.com/linuxermaster/cloudnativecosystem_mkdocs.git
mkdocs build --clean # 创建编译后的静态页面以及样式文件
mkdocs gh-deploy --clean  # push到gh-deploy分支下

此时，即可通过https://linuxermaster.github.io/cloudnativecosystem_mkdocs/访问

httpstat https://linuxermaster.github.io/cloudnativecosystem_mkdocs/

现在开始优化mkdocs以及配置主题样式了，这部分工作都在mkdocs.yml中完成

site_name: 云原生生态圈
nav:
  - 主页: "index.md"
  - 关于: "about.md"
  - 自动化: "devops.md"
theme: material
repo_url: https://github.com/linuxermaster/cloudnativecosystem_mkdocs.git
repo_name: "Opening on Github"
site_description: "这是一个mkdocs的demo测试知识库网站"
site_author: "Marionxue"
copyright: "1994 - 2020"

其中theme指定的是你的主题，这个主题就是我们常见到的traefik,nginx-ingress等在使用的官方文档的主题，如果使用它，你可能还需要额外的安装一下

pip3 install mkdocs-material

安装之后，执行mkdocs gh-deploy --clean即可访问网站的主题:

每次手动部署都是比较麻烦的，于是我们利用永久免费的travis来帮助解决这个问题:

language: python # Set the build language to Python

python: 3.6 # Set the version of Python to use

branches: master # Set the branch to build from

install:
  - pip install mkdocs mkdocs-material pymdown-extensions pygments # Install the required dependencies

script: true # Skip script (Don't use this if one already exists)

before_deploy:
  - mkdocs build --verbose --clean --strict # Build a local version of the docs

deploy: # Deploy documentation to Github in the gh_pages branch
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_API_KEY
  local_dir: site
  on:
    branch: master

然后我们使用GITHUB的账号登录travis, 地址是:https://travis-ci.org，在登录进去之后，我们选择合适的启用CICD

然后点击setting进入仓库的配置界面，设置以下三个环境变量

其中,GITHUB_API_KEY是从gitub上获取的Access Token,剩下的两个是用户名和密码。完成之后，我们就可以手动的触发以下构建:

紧接着，我们为了方便我们知道构建是否完成，我们在README.md文件上添加了一个构建的状态展示:

复制RESULT信息到readme.md中，即可显示每次构建的状态信息:

查看一下我们的构建历史