【极简教程】用 Mkdocs 库发布你的网站

最新推荐文章于 2025-03-26 12:54:08 发布

B417科研笔记

最新推荐文章于 2025-03-26 12:54:08 发布

阅读量1.7k

点赞数 1

分类专栏：科研经验分享

本文链接：https://blog.csdn.net/weixin_39274659/article/details/110735325

版权

科研经验分享专栏收录该内容

5 篇文章

订阅专栏

本文介绍如何使用Mkdocs将Markdown文档转化为网页，并部署到GitHub Pages。覆盖安装配置、自定义样式及数学公式支持等内容。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

Mkdocs

大家应该对这样页面风格的网站并不陌生：
在这里插入图片描述
这是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 Pages

首先，在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
发布到外网。

latex 输入

比如我们的博客要发布到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/