mkdocs踩坑记录

约 1025 字大约 3 分钟

2024-06-30

MkDocs踩坑记录

Latex

MathJax(数学) - Material for MkDocs (wdk-docs.github.io)

添加脚本到docs/javascripts/mathjax.js

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true,
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex",
  },
};

document$.subscribe(() => {
  MathJax.typesetPromise();
});

添加配置

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/mathjax.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

多层次列表

多层次列表(- 1.)无法正确显示

需要添加

markdown_extensions:
  - mdx_truly_sane_lists # 多级列表

不支持````c`格式的代码块

Code blocks - Material for MkDocs (squidfunk.github.io)

添加

markdown_extensions:
  - pymdownx.highlight: # 代码块语法高亮
      anchor_linenums: true # 启用行号
      line_spans: __span # 自定义行范围
      pygments_lang_class: true # 使用语言类名
  - pymdownx.inlinehilite # 行内代码高亮
  - pymdownx.tilde #删除线
  - pymdownx.snippets #代码片段, 没用过, 抄的配置
  - pymdownx.superfences #代码块增强

`<img>`格式图片引用出错

在平时写 markdown 时, 添加的截图经常会使用 typora 的右键进行缩放, 实际上是使用<img>标签来引用图片

这在 typora 和 vscode 中一切正常, 但是在用 mkdocs 部署时无法正确地引用到该图片

错误分析

参考StackOverflow 的回答

官方文档:
Markdown 允许文档作者在 Markdown 语法无法满足作者需求时，回退到原始 HTML。MkDocs 在这方面并不限制 Markdown。然而，由于所有原始 HTML 都被 Markdown 解析器忽略，MkDocs无法验证或转换包含在原始 HTML 中的链接(在这里就是我们图片链接)。当你在原始 HTML 中包含内部链接时，你需要手动将链接适当地格式化以适应渲染后的文档。

对于我上面的 testBlog, 生成的 url 为https://.../test/testBlog/ 这时, 这个 md 文件被视为一个目录

对于文档中<img src="test.assets/image-20240403162141023.png" alt="image-20220907225416746" style="zoom:33%;" />这一标签, 浏览器会去访问同一目录(test/testBlog/)下的图片(test/testBlog/test.assets/image-20240403162141023.png)

然而, 这个图片的实际路径并没有/testBlog

解决方案

同样参考StackOverflow 的回答

因为testBlog.md被转换为了一个目录, 这时候只需要让它不被转换

大佬给了一个配置项: use_directory_urls 该配置项会让testBlog.md展示为/testBlog.html文件而非/testBlog

后记

不要熬夜改 bug, 会变得神志不清
早该上 StackoverFlow 搜的 QAQ

博客(blog/posts)引用图片资源出错

问题描述

在presentation.md中, 我为了节约空间, 引用了fzu_cs_course/毕业设计/FZU-SINTEF-Beamer-Template.assets/preview_page-0001.jpg等图片文件树如下

docs
├── blog
│   ├── index.md
│   └── posts
│       └── presentation.md
└── fzu_cs_course
    └── 毕业设计
        └── FZU-SINTEF-Beamer-Template.assets
            ├── preview_page-0001.jpg
            └── ...

在presentation.md使用的相对路径引用为../../fzu_cs_course/毕业设计/FZU-SINTEF-Beamer-Template.assets/preview_page-0001.jpg 但是部署到服务器后, 图片无法显示

分析

检查编译出的site/blog可以发现文件夹结构发生了改变

site
├── blog
│   └── presentation.html # 没有posts文件夹了
└── fzu_cs_course
    └── 毕业设计
        └── FZU-SINTEF-Beamer-Template.assets
            ├── preview_page-0001.jpg
            └── ...

最终导致了相对路径解析出错

解决方案

用onerror事件来处理, 在解析错误时更换为正确的相对路径

<img src="../../fzu_cs_course/毕业设计/FZU-SINTEF-Beamer-Template.assets/preview_page-0001.jpg" 
  alt="Beamer Template Preview Page 1" 
  width="45%" 
  onerror="this.onerror=null;this.src='../fzu_cs_course/毕业设计/FZU-SINTEF-Beamer-Template.assets/preview_page-0001.jpg'"
/>

Blog 配置

Mkdocs Material 使用记录 - shafish.cn

mkdocs踩坑记录

MkDocs踩坑记录

Latex

多层次列表

不支持````c`格式的代码块

`<img>`格式图片引用出错

测试

测试文本

测试结果

错误分析

解决方案

后记

博客(blog/posts)引用图片资源出错

问题描述

分析

解决方案

Blog 配置