用Markdown写Hugo博客的一些小技巧

本文主要基于Hugo和Stack主题

基本语法

Stack主题Frontmatter Configs
Markdown Cheatsheet

还可以用到一些html的语法，但我暂时只学会了写<kbd>Enter</kbd>Enter

KaTeX与渲染问题

Stack主题支持KaTeX。KaTeX数学公式
注意如果需要显示KaTeX公式需要在Frontmatter里写math: true

渲染问题1：转义符号无法显示

Hugo有时会有无法正确渲染KaTeX的问题，我遇到的问题是用$$包裹的%或\%无法显示
上网搜索找到了相应的解决办法：Chlorine：在Hugo博客中正确渲染多行数学公式

如果用的也是Stack主题那么只需要添加这些代码就可以了：

 1markup:
  goldmark:
      extensions:
          passthrough:
              enable: true
              delimiters:
                  block:
                      - - \[
                        - \]
                      - - $$
                        - $$
                  inline:
                      - - \(
                        - \)
                      - - $ # 这里
                        - $ # 这里

注意输入百分号或下划线等需要转义的符号还是需要在前面加反斜杠：\% \_

渲染问题2：CDN被墙

更新一下：发现了新的问题，魔法上网KaTeX可以正确渲染，反之不能，排查后发现原因是主题文件夹\data\external.yaml中引用的CDN被墙
解决办法：
把主题文件夹\data\external.yaml（该路径仅对于Stack主题）下KaTeX的CDN地址换成墙内镜像站：

 1KaTeX:
  # - src: https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css
  - src: https://cdn.bootcdn.net/ajax/libs/KaTeX/0.16.9/katex.min.css
    integrity: sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV
    type: style
 6
  # - src: https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js
  - src: https://cdn.bootcdn.net/ajax/libs/KaTeX/0.16.9/katex.min.js
    integrity: sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8
    type: script
    defer: true
12
  # - src: https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js
  - src: https://cdn.bootcdn.net/ajax/libs/KaTeX/0.16.9/contrib/auto-render.min.js
    integrity: sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05
    type: script
    defer: true

修改后F5刷新一下本地预览页面应该就正常了

短代码

可以参见树响集：短代码应用，整理的很全

构建网页时不上传草稿

1# 构建排除草稿
2build: 
3    excludeDrafts: true

1---
2title: 这是一篇草稿文章
3description: 它只在本地预览时出现，构建网页时不会放入public文件夹
4date: 2025-10-17
5draft: true # true-草稿；false-非草稿
6---

本地预览时使用hugo server -D指令，则显示草稿；
构建时使用hugo指令，则忽略草稿（如果用hugo -D则上传草稿）

使用iframe嵌入网页

iframe可以用来嵌入外部网页或本地html。

基本格式：<iframe src="网址或本地html路径" style="width:100%;……css怎么写就怎么写"></iframe>

如果需要嵌入本地html，注意把文件放在项目根目录\static\下，src里写static文件夹下的路径

嵌入Godot制作的网页游戏

具体写在另一个帖子里了：第一个2D游戏

别的游戏引擎导出的项目文件应该也大差不差，但我没用过所以不乱说

我这个嵌入的游戏手机端是玩不了的，会卡在开始界面（虽然本来也没有设计给移动端玩，用的键盘操控），不知道有没有解决方案

嵌入思维导图

使用开源工具Markmap来实现。（GitHub ）

打开网址 https://markmap.js.org/repl ，左边栏可以用markdown语法写下需要整理成思维导图的内容，右边会生成思维导图。
点击Download as interactive HTML，将下载的文件放到项目根目录\static中

在.md文件中使用iframe嵌入下载的html文件：

1<iframe src="/p/markmap.html" 
2style="width:100%; 
3height:60vh; 
4border:none; 
5border-radius:20px;">
6</iframe>

不建议导出为svg嵌入，可能会有显示不完全的问题

多个表格横排

deepseek帮写的，仅记录
已发现手机上显示会横向超出屏幕的问题，但也不怎么用到就懒得想办法优化了

表格一

姓名	年龄	城市
张三	25	北京
李四	30	上海

表格二

产品	价格	库存
手机	2999	50
电脑	5999	20

表格三

月份	收入	支出
1月	1000	500
2月	1200	600

 1<div style="display: flex; gap: 20px; justify-content: space-between;">
 2
 3<div style="flex: 1;">
 4
 5表格一
 6| 姓名 | 年龄 | 城市 |
 7| ---- | ---- | ---- |
 8| 张三 | 25   | 北京 |
 9| 李四 | 30   | 上海 |
10
11</div>
12
13<div style="flex: 1;">
14
15表格二
16| 产品 | 价格 | 库存 |
17| ---- | ---- | ---- |
18| 手机 | 2999 | 50   |
19| 电脑 | 5999 | 20   |
20
21</div>
22
23<div style="flex: 1;">
24
25表格三
26| 月份 | 收入 | 支出 |
27| ---- | ---- | ---- |
28| 1月  | 1000 | 500  |
29| 2月  | 1200 | 600  |
30
31</div>
32
33</div>