#前端 #mkdocs

mkdocs部署使用详细说明¶

约 3451 个字 424 行代码预计阅读时间 17 分钟

无意间看到了杭州市疾控中心微生物检验科病原微生物测序实验室的生信教程，第一眼就被它的博客主题吸引，看到页脚的Made with Material for MkDocs，从此陷入了mkdocs的沼泽。这里将个人对mkdocs的使用探索过程做一个详细记录分享，希望喜欢mkdocs朋友可以用它做出自己心目中的知识库系统、产品手册或者博客；此外，分享的另一个原因是只为了自己的方便，我怕后续自己的服务器崩溃或者后续更换云服务器，避免进行知识系统迁移时从头学习配置mkdocs，毕竟从自己搜索到的中文相关教程来看，大佬们分享的资料均只是简单的安装，没有后续网站的详细配置教程，或许他们不屑于分享出来吧。

关于mkdocs¶

MkDocs 是一款快速、简单、华丽的静态网站生成器，适用于构建项目文档；它使用Python作为后端，并提供了简单易用的Markdown语法来编写文档内容。MkDocs的前端使用Bootstrap和Jinja2模板引擎，可以轻松地生成响应式的文档网站。

MkDocs旨在解决文档编写和展示的问题。传统的文档编写方式可能需要使用复杂的排版工具或网页开发技术，而MkDocs通过简化文档的编写和展示流程，使得创建和维护漂亮的文档网站变得更加容易。它提供了一种便捷的方式来组织和呈现文档内容，帮助开发者和团队快速构建专业的文档网站

特点：

简单易用：MkDocs提供了简洁的Markdown语法和直观的配置选项，使得文档的编写和生成变得简单易用；文档源码使用 Markdown 编写，一个 MD 文件对应一个 HTML 页面；
响应式设计：MkDocs使用Bootstrap和Jinja2模板引擎来构建文档网站，生成的网站具有良好的响应式设计，适应不同设备的屏幕大小；
可定制性：通过配置mkdocs.yml文件，可以自定义主题、导航栏、页面布局、添加插件等，此外还支持自定义的css和js接口，可以实现文档网站的个性化定制；
任意托管：构建完全的静态HTML站点，可以托管到 GitHub pages 等任意地方；
丰富主题：Github MkDocs Themes汇总了大量的的主题，具有活跃的社区，github：18.8k+ star；
即时预览：内建的开发服务器使你在撰写文档的时候就即时预览；
交叉索引：使用 MkDocs 链接语法创建交叉索引，即可实现文档之间任意引用；
应用广泛：MkDocs适用于各种类型的文档网站创建场景；它可以用于开发者编写项目文档、API文档、用户手册、技术博客等。无论是个人开发者还是团队，使用MkDocs可以快速创建漂亮且易于维护的文档网站，方便展示和分享知识。

写在前面¶

为了方便后续使用，推荐先将个人云服务器的8000号端口进行开放，无论是通过云服务器的控制面板(推荐)还是后台的开放均可以，mkdocs默认占用的是8000端口，这里个人开放的是8001。

安装¶

mkdocs本质上是一个python包，直接可使用pip进行安装，腾讯云服务器上，如果个人账户直接进行安装可能会因为权限导致无法安装，但是每次用sudo命令很麻烦，这里索性安装在个人的目录(但是谨记后续可能会找不到mkdocs命令，后续得使用：python3 mkdocs替换mkdocs)；其实如果只想要mkdocs，以下第一个命令安装即可，但默认的mkdocs主题容易造成视觉疲劳，这里直接安装mkdocs的王牌主题：material theme，更多主题详见：Github MkDocs Themes。此外，插件mkdocstrings会提取Python代码中的docstring用来生成文档，这无疑是非常方便的，这里推荐将三个包一起安装，避免后续依赖包折腾。

Bash

 pip install -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com mkdocs -U
 pip install -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com "mkdocstrings[python]" -U 
 pip install -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com mkdocs-material -U

总结一下：其实无论是mkdocs，还是它的主题，还是插件均是python包，易安易用，真的非常方便。

建站¶

所谓的建站，就是在服务器上找一个存储目录并创建自己的站点名称文档的文件夹即可，这里创建一个test的站点，创建命令如下：

Bash

cd /data/test && python3 -m mkdocs new ./

如上图，一个简单的mkdocs站点就建立完成，其中docs文件夹用于存放文档，即md文件，mkdocs.yml就是站点的配置文件，可以在该文件中配置各种相关参数，例如：主题参数，logo参数，自定义css/js，插件，站点信息，页面布局管理等等。

此时如果你的端口已开放，例如：8001端口，直接可以命令行输入以下命令启动mkdoc渲染服务，然后再服务器打开：ip:8001就可以看到了自己的站点主页，其中ip是你的服务器的IP。

Bash

###这里有一个坑：如果输入：mkdocs serve -a 0.0.0.0:8001 可能会报错，提示mkdocs找不到，可能是因为安装到自己的目录造成的
python3 -m mkdocs serve -a 0.0.0.0:8001

配置¶

初始站点成功创建后，接下来就可以在mkdocs.yml中进行各种参数修改，这里以以下几个部分进行讲解，可能并不全，毕竟个人的站点也不是对所有地方都做了魔改。

提醒一下：注意yaml的格式缩进问题，yaml对缩进有严格要求，可以使用vscode或者其他编辑器的格式化快捷键进行格式化。

主题修改&色彩风格修改：

Markdown

##主题配置
theme:
  name: material ####主题名称
  language: en ###修改语言
  favicon: images/favicon.ico ####使用自定义的网站标题图标
  logo: images/logo.png ####使用自定义的网站url显示图标

  # icon:

####修改主题的颜色风格&亮度模式
  palette:
      # 切换到亮色
      - media: "(prefers-color-scheme: light)" # 根据系统的颜色模式自动切换
        scheme: default
        primary: default
        accent: default
        toggle:
            icon: material/weather-night
            name: 切换到暗色模式

      # 切换到暗色
      - media: "(prefers-color-scheme: dark)"
        scheme: slate
        primary: default
        accent: default
        toggle:
            icon: material/weather-sunny
            name: 切换到亮色模式
  features:
      - navigation.instant # 现在页面不会跳转,而是类似单页应用,搜索和各种跳转都是在当前页面完成,对美观有很大帮助
      - navigation.tabs # 顶部显示导航顶层nav（也就是第一个节点）
      # - navigation.tracking # 页面滚动时，导航栏高亮当前页面
      # - navigation.sections # 使导航栏分块
      # - navigation.expand # 展开导航，不进行折叠
      - navigation.tabs.sticky # 滚动是隐藏顶部nav，需要配合navigation.tabs使用
      - navigation.prune # 只渲染当前页面的导航
      - navigation.path #显示当前页面的层级路径(默认页面顶端)
      - toc.follow # 滚动的时候侧边栏自动跟随
      # - toc.integrate #直接在左侧的toc中展示页面的中的目录，不进行右侧toc的生成，如果想右侧生成当前页面的导航，需要禁用该配置
      - navigation.top # 返回顶部按钮
      - search.suggest # 搜索时，提供补全建议
      - search.highlight # 搜索结果高亮
      - search.share # 搜索结果分享
      - navigation.footer # 页脚提示下一章
      - content.code.copy # 代码段上的赋值按钮
      - content.code.annotate #代码注释
      - content.code.select #代码选择

需要注意的是，在修改相关主题和插件前，相关的python包应该提前装好，否则修改保存mkdocs.yml生效后如不能加载到相关的包，会报错导致解析错误和404错误。此外，值得一提的是theme下的features部分定义，你可以将它认为是一些内置的网页优化小组件，例如：toc布局，代码块美化&注释等都可以直接在features中开启。

markdown拓展配置

Markdown

##修改配置markdown相关的扩展
markdown_extensions:
    - admonition # 警告语法
    - def_list
    - footnotes
    - abbr
    - pymdownx.caret
    - pymdownx.mark
    - pymdownx.tilde
    - md_in_html ####支持图片对齐，https://squidfunk.github.io/mkdocs-material/reference/images/?h=right#image-alignment-right
    - attr_list
    - pymdownx.arithmatex: # latex支持
          generic: true
    - toc:
          permalink: true # 固定标题位置为当前位置
          toc_depth: 5 # 目录深度
    - pymdownx.highlight: # 代码块高亮
          anchor_linenums: true
          linenums: true # 显示行号
          use_pygments: true # 代码高亮
          pygments_lang_class: true
          auto_title: true # 显示编程语言名称
          linenums_style: pymdownx-inline # 行号样式,防止复制的时候复制行号
          line_spans: __span

    - pymdownx.betterem # 强调美化,比如**text**会被美化
    - pymdownx.caret # 上标和下标
    - pymdownx.mark # 上标和下标
    - pymdownx.tilde # 上标和下标
    - pymdownx.keys # 显示按键组合
    - pymdownx.critic
    - pymdownx.details # 可以折叠的代码块 ??? note 可以让警告变成折叠的
    - pymdownx.inlinehilite
    - pymdownx.snippets
    # - pymdownx.superfences
    - pymdownx.magiclink # 自动识别链接
    - pymdownx.smartsymbols # 智能符号
    - pymdownx.snippets # 代码段
    - pymdownx.tasklist:
          custom_checkbox: true # 自定义复选框
    - pymdownx.emoji:
          emoji_index: !!python/name:material.extensions.emoji.twemoji
          emoji_generator: !!python/name:material.extensions.emoji.to_svg
    # - pymdownx.superfences: # 代码块中支持Mermaid
    #       custom_fences: # 支持 Mermaid
    #           - name: mermaid
    #             class: mermaid
    #             format: !!python/name:mermaid2.fence_mermaid_custom
    - pymdownx.superfences: # 代码块中支持vegalite
          custom_fences: 
              - name: vegalite  ###vegalite绘图
                class: vegalite
                format: !!python/name:mkdocs_charts_plugin.fences.fence_vegalite
              - name: mermaid   ###Mermaid绘图
                class: mermaid
                format: !!python/name:mermaid2.fence_mermaid_custom
    - pymdownx.tabbed:
          alternate_style: true
          combine_header_slug: true
    - pymdownx.tasklist:
          custom_checkbox: true
          clickable_checkbox: true
    - meta # 支持Markdown文件上方自定义标题标签等
    - tables

3. 插件配置

外置mkdocs插件，为了解决原生mkdoc某些功能的不足，官方和很多大佬开发了一些拓展包——插件来完善丰富mkdocs的功能。

YAML

plugins:
  - monorepo
  - search
  - markdown-exec
  - tags:
      tags_file: tags.md
  # - projects:     ###仅insider版本支持
  #     projects_dir: bioinfo
  - mermaid2: ###支持mermaid2流程图，mkdocs内置mermaid仅支持insider版本,这里用的是github的包
      version: '10.2.0'
      javascript: javascripts/mermaid.min.js ###1.1版本之后的mkdocs-mermaid2-plugin，js需要在这里定义
      arguments:
        securityLevel: 'loose'
        theme: 'dark'
        # theme: |
        #     ^(window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light'
  - glightbox ###图片zoom操作，即图片的点击放大缩小可视化
  - charts ### 基于vegalite的动态可视化绘图

mkdocs的插件只要提前安装后，即可在配置文件中plugins区块下进行添加模块名称(插件名称)即可启用，对于部分插件可能需要配置额外的js和superfences属性(markdown_extensions区块下配置，参考上述的markdown_extensions配置)，注释掉相关插件的启用行即可停用相关插件。

mkdocs的插件分为两种，一种是官方自己开发或衍生的插件，即内置插件(Built-in plugins)，目前支持的内置插件详见官网的Plugins页面：

但是这里需要特别提醒的是，并不是所有内置插件都是免费可用的，insider版本的mkdocs支持所有功能，我们普通标准版本的mkdocs部分插件是不可用的，需要进行官方的赞助和授权才能开启，经个人测试发现：Blog/Projects等插件是insider版本才开放，标准版的mkdocs只能用其他平替方案，即第二种插件类型——非官方插件，例如上述的配置文件中的glightbox/charts/mermaid2/monorepo等插件，目前很多非官方插件，由于使用的频率很高&使用群体多，官方也在考虑将其纳入内置列表(eg:mermaid2,insider版本支持)，坐等mkdocs更新吧。

目前个人使用的官方内置插件包括：

search插件：允许用户搜索站内文档，它由 lunr.js 提供支持，这是一个轻量级的浏览器全文搜索引擎，无需外部服务，甚至在构建离线文档时也能使用；

tags：增加了对页面进行分组，并可通过搜索和专用标签索引发现它们。如果文档较多，标签可以帮助您更快地发现相关信息；对于tag的启用也非常简单，在plugins模块下添加启用，同时添加tags_file: tags.md属性，并在最上层的docs目录下创建一个空白的tags.md文件即可，在撰写markdown时在文档最顶层用tags标签即可进行页面的标签自定义。

Markdown

---
tags:
  - mkdocs
---
我只是一个测试

这里重点说明推荐以下monorepo插件，我认为他是官方insider-Projects插件的最好平替，它们都是为了站点内的项目将主项目拆分成多个不同项目的功能，可以同时构建这些项目，并将它们作为一个整体进行预览，简而言之就是可以将站内的项目文档进行分类管理，并都放在docs目录下，否则当站内的页面激增后，你会发现docs的管理将会非常的麻烦，此外在mkdocs.yml文件中进行目录结构的配置是也非常不方便，多个项目，推荐还是分而治之。

至于monorepo的使用也非常简单，只要在plugins区块下添加启用，然后就可以个每一个单独的项目就可以单独存放在指定的目录，对于该项目的文档管理也是可以独立的，以下是一个示例：

个人的第三方插件安装命令：

Bash

##基于altair绘图
pip install mkdocs-charts-plugin -U
pip install "altair[all]" -U -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

#为了在markdown的code block下执行python语句，这操作简直不要太酷炫
pip install "markdown-exec[ansi]" -U -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

#为了绘制思维导图
pip install -U -i http://mirrors.aliyun.com/pypi/simple/ mkdocs-mermaid2-plugin

4. 自定义css/js配置

Markdown

# 自定义css
extra_css: 
  - stylesheets/extra.css

# 自定义js
extra_javascript:
  # - https://cdn.jsdelivr.net/npm/vega@5  ###charts插件的配套js，https://timvink.github.io/mkdocs-charts-plugin/
  # - https://cdn.jsdelivr.net/npm/vega-lite@5
  # - https://cdn.jsdelivr.net/npm/vega-embed@6
  - javascripts/vega.min.js ###为了加速，将上诉三个js下载到本地
  - javascripts/vega-lite.min.js
  - javascripts/vega-embed.min.js

这里重点说明一下自定义css和js文件的存放目录：在docs目录下创建stylesheets和javascripts两个文件夹，分别存放自定义的css和js，可参考上述示例命名。

对于mkdocs的高级玩家，可以对自己页面上各种html元素做想要的自定义，只要获取到相关的html元素的id就可以为所欲为，至于怎么获取相关元素的class/id信息，我是用使用chrome浏览的查看源码功能获取的，当然也有很多浏览器插件可以快速获取，例如：PageRip浏览器插件。

对自定义部分，个人的魔改并不是很多，主要包括以下几个部分： - 为了使页面效果更加具有逻辑和层级结构，自定义了h1-h4 css tag，自定义目前看起来依然很丑，斯是陋室，为吾德馨，先将就着吧，等哪天看到大佬的酷炫自定义再去抄作业； - 自定义table样式； - 自定义背景，为了模仿微信公众号的网格背景； - 自定义了页面宽度比例详细的的内容可参考：

CSS

/* 中部内容面板宽度 */
div.md-content{
  min-width: 70%;
}

/* 表格自定义优化 cite:https://blog.ktz.me/making-mkdocs-tables-look-like-github-markdown-tables/ */
th, td {
  border: 1px solid var(--md-typeset-table-color);
  border-spacing: 0;
  border-bottom: none;
  border-left: none;
  border-top: none;

  width:auto;
  min-width:10px;
}
th {
  background-color: #4051B5;
  color: white;
}

.md-typeset__table {
  line-height: 1;
}

.md-typeset__table table:not([class]) {
  font-size: .74rem;
  border-right: none;
}

.md-typeset__table table:not([class]) td,
.md-typeset__table table:not([class]) th {
  padding: 9px;
}

/* light mode alternating table bg colors */
.md-typeset__table tr:nth-child(2n) {
  background-color: #f8f8f8;
}

/* dark mode alternating table bg colors */
[data-md-color-scheme="slate"] .md-typeset__table tr:nth-child(2n) {
  background-color: hsla(var(--md-hue),25%,25%,1)
}

/* #### */

.basediv {
  float: right;
  display: block;
  max-width: 60%;
  height: auto;
  margin: 10;
  float: none!important;
}

div.wolai-row { 
  display: flex; 
}

/* 设置inline-code的style,https://stackoverflow.com/questions/57060610/how-to-change-inline-code-color-in-mkdocs */
.md-typeset p > code {
  padding: 0.2em 0.4em;
  color: #84AADC;
  border-radius: 4px;
  font-weight: 600;
}

/* // ####设置背景： */
body{
  /* // ###方案1：https://mp.weixin.qq.com/s/svg1eOCyi3u6TmemASHVwA */
  /* padding: 10px; 
  background-size: auto; 
  background-image: url(http://mmbiz.qpic.cn/mmbiz/yqVAqoZvDibG84oQ3rQ0C1bdcgrh9SZUj1NJvlvFIymN1lfkwH04ib0m11YWt9aeDGQiaLnbx8NibKuCf4XObhSiaQA/0?wx_fmt=png); 
  box-sizing: border-box; 
  background-position: center center; 
  background-repeat: repeat repeat; */

  /* // ###方案2：https://mp.weixin.qq.com/s/o5srQXisTqs2wcRAvq7oKw */
  margin-bottom: 0px;
  padding-left: 10px;
  padding-right: 10px;
  background-attachment: scroll;
  background-clip: border-box;
  background-image: linear-gradient(90deg, rgba(50, 0, 0, 0.03) 0%, rgba(255, 255, 255, 0) 11.49%), linear-gradient(360deg, rgba(50, 0, 0, 0.04) 0%, rgba(255, 255, 255, 0) 12.16%);
  background-origin: padding-box;
  background-position: 0% 0%;
  background-repeat: repeat, repeat;
  background-size: 20px 20px, 20px 20px;
  width: auto;
  /* font-family: Optima, PingFangSC-light, serif;
  font-size: 16px; */
  /* color: rgb(0, 0, 0); */
  line-height: 1.5em;
  word-spacing: 0em;
  letter-spacing: 0em;
  word-break: break-word;
  text-align: left;
  visibility: visible;
}

/* h1 {
  display: table;
  margin: 30px auto 20px auto !important;
  padding: 10px !important;
  background-image: linear-gradient(to left, rgb(253, 213, 231), rgb(194, 226, 249));
  border-width: 1px;
  border-radius: 10px;
  box-shadow: 3px 3px 3px #ccc;
  font-size: 20px !important;
  text-align:center;
}

h2 {
  display: table;
  margin: 30px auto 20px auto !important;
  padding: 0px 10px !important;
  border-bottom: 5px solid #205792;
  text-align: center;
  font-size: 18px !important;
}

h3 {
  border-bottom: #2b2b2b;
}

h3:before {
  content: "✒️ ";
}

h4:before {
  content: "✏️";
}

h5 {
  background-color: #f1f1f1;
  border-left: 5px solid #fff;
  padding-left: 5px !important;
  box-shadow: -3px 0px #205792;
}

h6 {
  border-left: 5px solid rgba(0, 0, 0, 0);
  box-shadow: 0px 2px #205792;
} */

h2:after, 
h3:after, 
h4:after {
  position: absolute;
  content: "";
  left: 0;
  top: 0;
  bottom: 0;
  width: 6px;
  border-radius: 2px;
  box-shadow: inset 0 1px 1px rgba(0,0,0,0.5), 0 1px 1px rgba(255,255,255,0.3);
}

/* ########################################################## */
/* https://tympanus.net/codrops/2012/11/02/heading-set-styling-with-css/ */
h2:after { background: #4051B5; }
h3:after { background: #4051B5; }
h4:after { background: #4051B5; }

h1 {
  font-size: 36px;
  line-height: 40px;
  margin: 1em 0 .6em 0;
  font-weight: normal;
  color: black;
  /* font-family: 'Hammersmith One', sans-serif; */
  text-shadow: 0 -1px 0 rgba(0,0,0,0.4);
  position: relative;
  color: #4051B5;
}

h2 {
  margin: 1em 0 .6em 0;
  padding: 0 0 0 20px;
  font-weight: normal;
  color: black;
  /* font-family: 'Hammersmith One', sans-serif; */
  text-shadow: 0 -1px 0 rgba(0,0,0,0.4);
  position: relative;
  font-size: 30px;
  line-height: 40px;
}

h3 {
  margin: 1em 0 .6em 0;
  padding: 0 0 0 20px;
  font-weight: black;
  color: black;
  /* font-family: 'Hammersmith One', sans-serif; */
  text-shadow: 0 -1px 0 rgba(0,0,0,0.4);
  position: relative;
  font-size: 24px;
  line-height: 40px;
  /* font-family: 'Questrial', sans-serif; */
}

h4 { 
  margin: 1em 0 .6em 0;
  padding: 0 0 0 20px;
  font-weight: normal;
  color: black;
  /* font-family: 'Hammersmith One', sans-serif; */
  text-shadow: 0 -1px 0 rgba(0,0,0,0.4);
  position: relative;
  font-size: 18px;
  line-height: 20px;
  /* font-family: 'Questrial', sans-serif; */
}

5. 额外信息配置

额外信息可以在extra区块下进行添加，可以有图标的定义，表情包的定义，当然更为重要的是一些外链网站的定义，例如个人的twitter或者github账户的外链等，参考示例如下

YAML

extra:
  analytics:
    provider: google
    property: !ENV GOOGLE_ANALYTICS_KEY
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/xxx
    # - icon: fontawesome/brands/twitter
    #   link: https://twitter.com/squidfunk

6. 网站基本信息配置

这没什么好说明的，按照自己的预期进行修改即可，以下是一个参考：

YAML

#######配置站点基本信息
repo_name: openbioinfo.site
repo_url: https://openbioinfo.site
site_name: laoxu的生信wiki
site_description: 旨在记录分享个人工作经验和学习笔记，以及自己的一些瞎折腾，期望构建一个生物信息的速查库
site_author: laoxu
site_url: https://openbioinfo.site
copyright: Copyright © 2024 <a href="https://openbioinfo.site">Powered by openbioinfo.site 版权所有</a>

7. 页面结构布局配置

页面布局配置主要是在nav区块下进行配置，个人觉得与python字典结构类似，就是一些键值对，所谓的键就是网页中要展示的导航栏名称，值就是相关的markdown文件或者yml文件，参考示例如下：

YAML

nav:
  - 首页:
    - 关于笔记: index.md
  - 生信系统笔记:
    - ...: blueprint.md
    - 转录组: '!include ./bioinfo/transcriptome/mkdocs.yml'
    - 基因组: '!include ./bioinfo/genome/mkdocs.yml'
    - 表观组: '!include ./bioinfo/epigenome/mkdocs.yml'
    - 蛋白组: '!include ./bioinfo/proteomics/mkdocs.yml'
    - 代谢组: '!include ./bioinfo/metabolomics/mkdocs.yml'
    - 单细胞组学: '!include ./bioinfo/singlecell/mkdocs.yml'
    - 多组学联合: '!include ./bioinfo/multiomics/mkdocs.yml'
    - 数据库: '!include ./bioinfo/dbs/mkdocs.yml'
    - 公共数据系列: '!include ./bioinfo/public/mkdocs.yml'
    - 编程: '!include ./bioinfo/programme/mkdocs.yml'
    - 机器学习: '!include ./bioinfo/machinelearn/mkdocs.yml'
    - 系统&服务器: '!include ./bioinfo/os/mkdocs.yml'
  - 实验手册: '!include ./bioinfo/experiment/mkdocs.yml'
  - 分类:
    - tags: tags.md
  - 关于我:
    - whoami: about.md

如果学会了上述的安装配置和简略的个性化，基本的mkdosc搭建就基本酵素了，可做出大概的站点框架了，后续就是撰写添加文档和布局调整；如果想要成为高级玩家，赞助或者自己撰写相关的模块(需要python+css+js等知识)来完善功能了；后续如果笔者有时间，想研究下文档的发布，类似于Blog的功能，以及魔改目前的tag功能，个人觉得tag页面不是合理。

启动服务¶

当你的文档撰写完成后，对于mkdocs的就可以进行部署托管了，可以部署到github等平台上，鉴于我是自己买的云服务器，没有做部署到github的测试，也不打算部署到GitHub上，首先是因为国内访问速度慢，其次是部署到github上，它就不再属于你了，而是google或者GPT或者某个大模型了，最后再来一个收费卖给你，只问你亏不亏。

这里进行服务器部署：

生成文档

Bash

# 构建文档站点
python3 -m mkdocs build
###记得提交后台和修改自己的端口
python3 -m mkdocs serve

配置域名和反代理

为了实现域名访问自己的站点，需要提前准备国内或者国外的域名，国内需要备案，如实提交资料，静待一周即可；

为了避免暴露自己的端口号，可以基于nginx进行反代理，可以参考大佬的文章：

https://mp.weixin.qq.com/s/ygkA7cE-fYqDaF9fFD8gcw

https://mp.weixin.qq.com/s/Vf8-K8EnKfr3hdUpC6k3sA

其他补充¶

mkdocs内置了很多的个性化语法(eg：::: src.token_counter.token_count)和网页布局(eg:图片对齐)和网页元素，需要的可以到官网进行学习。

这里再补充一些不错的知识点和学习网站：

vega-lite可视化在线测试网站，不懂vega-lite可视化语法的，这个网站强烈推荐。

Vega Editor

mkdoc第三方使用教程，里面介绍了很多关于魔改mkdocs的技能知识点。

MkDocs MagicSpace

mkdocs-Icon设置

icons-emojis,直接去该页面搜索复制后到md文件中粘贴即可使用，其他编辑器或者图标库的Icon再mkdocs中并不一定支持。