大家应该对这样页面风格的网站并不陌生： 
这是Keras文档的中文文档网站， 还有大名鼎鼎的爬虫库Selenium的中文文档 
以及许许多多的知名库/包的官方网站， 都是这样的页面风格。 这是因为， 他们都出自一个python库： Mkdocs 之手。 这个库就是支持以Markdown语法（名字也是mkdocs）来写文档， 并帮助你流水线般地生产成网页。 正如markdwon语法的初衷是希望人们更专注于内容而非格式， Mkdocs也是如此。 你可以用Django， 用Flask 生成更精美的网页， 但没有必要。 因此， Mkdocs来负责把文档生成为网页， 你则专注于内容， 而非排版，布局， 调色…
这篇博客就用最简单的教程讲解下从零上手Mkdocs的简单实用。
安装 和 起步首先， 用 pip install mkdocs命令下载Mkdocs库。 我用的是 Pycharm， 就以此为例了。 随便新建一个工程：我随便起了一个名字Mybook，这个随意， 在pycahrm下打开。 
点击Pycharm页面下方的terminal或者Alt+F12, 唤起命令行终端。 
在命令行输入mkdocs nwe my-project， 其中my-project是你自定义的项目名，得到： 
目录则变为： 
这是mkdocs自带的默认文档页面， 现在我们可以看看他对应生成的html文件长啥样： 先进入项目目录下： 输入cd my-project 继续在命令行输入： mkdocs serve， 得到效果如下： 
OK， 现在已经可以通过打开 http://127.0.0.1:8000/ 来看看文档网页了，下图就是Mkdocs的默认页面。 
显然，我们可以通过修改项目下的内容， 对网页进行修改， 例如：
- 修改网页名称： 打开
mydocs.yml文件， 修改site-name：
你会发现，刚刚的网页马上对应的修改了。 注意， 这个过程中不需要你重新启动服务器什么的，这是自动检测到的， 非常方便， 所见即所得。 
同理， 可以通过修改.md文件来改进内容什么的， 这里先不赘述， 可以取官方教程里看看， 我们现在要完成把它发布到网上，而非自娱自乐。
首先，在github网站上新建一个库， 
将其clone到本地。 然后，**把刚刚my-project下的所有文件复制到B417_blogs目录下。 在pycharm中打开 B417_blogs， 目录如图： 
我们通过git， 把我们的操作commit并push到github上（这个网上教程很多， 就不赘述了）。我用的是github桌面版进行同步。 
回到pycharm下， 按Alt +F12打开命令行终端， 输入mkdocs gh-deploy： 
等待mkdocs自动把文档生成网页文件（html，css等， 存放在site目录下）同步到github。 完成后为： 
此时，点击该网址， 就得到和刚刚在 127.0.0.1下看到的一样的网页啦， 但区别在于， 这次的是发布在了外网上， 所有人都能通过网址进行访问。 https://TianLin0509.github.io/B417_blogs/
想把自己的文档发布成网页， 最简单的流程就是用mkdcos， 然后通过markdown语法书写。 在自己本地端确认网页后， 再通过github pages发布即可。
后续修改已经发布到github pages的网页， 如果还想修改，仍在pycharm的命令行下， 输入 mkdocs build --clean（很重要！否则页面看上去没有修改）来清除过期的页面。 然后再次运行 mkdocs gh-deploy 发布到外网。
比如我们的博客要发布到github pages中， 需要有许多的数学公式。 如何让本地的markdown支持？
- 下载相关包 在pycharm命令行输入
pip install pymdown-extensions - 修改mcdocs.yml文件
extra_javascript:
- javascripts/config.js
- https://polyfill.io/v3/polyfill.min.js?features=es6
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
markdown_extensions:
- pymdownx.arithmatex:
generic: true
如上， 加入下面两段代码即可。 然后创建javascripts文件夹， 并在文件夹下新建config.js文件。
window.MathJax = {
tex: {
inlineMath: [["\\(", "\\)"]],
displayMath: [["\\[", "\\]"]],
processEscapes: true,
processEnvironments: true
},
options: {
ignoreHtmlClass: ".*|",
processHtmlClass: "arithmatex"
}
};
然后发现， 在markdown文档中可以直接使用latex语法输入公式了。 原攻略参考官方网站: https://squidfunk.github.io/mkdocs-material/reference/mathjax/
