跳转至

MkDocs高亮功能使用本地代码

MkDocs自带主题就支持语法高亮,且默认开启。主要有以下几个设置项:

MkDocs高亮介绍

  • highlightjs:是否开启代码高亮的总开关,默认为true
  • hljs_style:代码高亮的样式,默认为github总共有79种样式
  • hljs_languages:代码高亮支持的语言,不同语言会载入不同的js文件。我开启了高亮bash及javascript。
    配置文件如下:
    1
    2
    3
    4
    5
    6
    7
    theme:
        name: mkdocs
        highlightjs: true
        hljs_languages:
            - yaml
            - bash
            - javascript
    

使用本地文件实现高亮

默认的代码高亮功能使用了CDN载入不同的js及CSS代码,查看网页HEAD部分的源文件,可以看到如下代码:

本来使用mkdocs就是开中了其静态文件,载入快的优点,然而使用了CDN后速度优势就不那么明显了,再加上这个代码高亮功能所使用的CDN在国内访问起来速度真心不理想,偶尔还可能连不上。

解决办法当然就是禁用CDN,将需要加载的文件置于本地服务器,随同静态文件从同一个服务器一并加载。

修改配置文件mkdocs.yml

1
2
3
4
theme:
    name: mkdocs
    custom_dir: mkdocs-zimo/
    highlightjs: false
以上配置,使用默认的mkdocs主题,并且添加自定义的目录(custom_dir):mkdocs-zimo,关闭代码高亮功能(highlightjs)

下载CDN代码文件到本地目录

如上面图片所示,下载js或者css代码文件,根据不同语言代码高亮的需求,分别下载相应的代码。除了不同语言所需的js文件外,还需要下载两个公用文件:highlight.min.jsgithub.min.css

修改main.html

修改自定义目录下的mail.html(/mkdocs-zimo/mail.html),在末尾添加:

1
2
3
4
5
6
7
8
9
{% block libs %}
    {{ super() }}
    <link rel="stylesheet" type="text/css" href="{{ base_url }}/css/github.min.css">
    <script src="{{ base_url }}/js/highlight.min.js"></script>
    <script src="{{ base_url }}/js/yaml.min.js"></script>
    <script src="{{ base_url }}/js/bash.min.js"></script>
    <script src="{{ base_url }}/js/javascript.min.js"></script>
    <script>hljs.initHighlightingOnLoad();</script>
{% endblock %}
需要注意的是对应的各文件的路径以及末尾的<script>hljs.initHighlightingOnLoad();</script>