跳到主要内容

vitepress语法 vs hugo短代码

最后更新于:

image-20260730064057.avif

vitepress语法 vs hugo短代码

问题

 1自己OneBlog目前的自定义markdown语法(告警容器风格和代码折叠)是按vitepress语法写的:(然后转换到hugo可以识别到的语法的)
 2例如:
 3告警容器风格
 4::: info
 5这是一条info,自定义格式:info+空格+自定义文字
 6:::
 7
 8::: tip 提示
 9这是一个提示,自定义格式:tip+空格+自定义文字
10:::
11
12::: warning 警告
13这是一条警告,自定义格式:warning+空格+自定义文字
14:::
15
16::: danger 危险
17这是一个危险警告,自定义格式:danger+空格+自定义文字
18:::
19
20::: details 点我查看
21这是一条详情,自定义格式:details+空格+自定义文字
22:::
23
24
25代码
26::: details 点我查看
27这是一条详情,自定义格式:details+空格+自定义文字
28:::
29
3001.这个从vietpress markdown语法转换成hugo能识别到的语法 很耗时嘛,或者影响hugo性能不?
3102.hugo的短代码语法是什么样的呢,听说很强大是吗?
3203.那么你推荐我是继续用vietpress markdown语法呢,还是用hugo的短代码呢?(个人体验了下hugo短代码,感觉还是不如vitepress语法简洁友好,hugo短代码要写的代码有点多呀。。)

回答

结合 OneBlog 现有流水线,直接说结论:


01. 转换耗时吗?会影响 Hugo 性能吗?

几乎不影响 Hugo 渲染性能。 转换发生在 Hugo 之前(build/watch 预处理),不是 Hugo 逐页解析时额外负担。

流水线大致是:

1content/*.md(::: tip)
2  → hugo-teek-tools convert
3  → .content-vp-converted(
4<div class="custom-block info"><p class="title custom-block-title">信息</p><p>)<br>  → fix-custom-block-markdown.mjs(常再写成 HTML)<br>  → Hugo 读转换后的目录构建</p><div class="highlight" data-lang="text"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text">&#10;&#10;&#10;| 环节                               | 负担                     |&#10;| :--------------------------------- | :----------------------- |&#10;| `convert`(Go,整篇解析 + 改写块) | 中等,但一次预处理       |&#10;| Node / shell 修补脚本              | 轻到中等(正则)         |&#10;| Hugo 正式渲染                      | 基本只吃已经转换好的内容 |&#10;&#10;所以:&#10;&#10;- 对 Hugo 站点性能:几乎无感(最终多半是&lt;u&gt;短代码或预渲染 HTML&lt;/u&gt;)。&#10;- 对你自己的体验:主要是 构建/热更新多一步;文章少时通常秒级,文章很多、频繁保存时 watch 会多一点点延迟,一般仍可接受。&#10;- 真正吃时间的是「全站重新 convert」,不是 Hugo 本身慢。&#10;&#10;------&#10;&#10;## 02. Hugo 短代码长什么样?强不强?&#10;&#10;OneBlog 里告警对应的就是例如:&#10;</code></pre></div><p>bash<br>{{&lt; alert tip &quot;提示&quot; &gt;}}<br>这是一个提示<br>{{&lt; /alert &gt;}}</p><div class="highlight" data-lang="text"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text">&#10;&#10;&#10;或命名参数版:&#10;</code></pre></div><p>bash<br>{{&lt; custom-block type=&quot;tip&quot; title=&quot;提示&quot; &gt;}}<br>这是一个提示</p></div>

对比 VitePress:

1::: tip 提示
2这是一个提示
3:::

短代码确实很强:可传参、嵌套、读站点配置、调 partial、复杂 HTML/逻辑都可以放进 layouts/shortcodes/。适合卡片墙、Tabs、复杂组件

但对 告警 / details 这种高频写作语法,短代码偏「模板感」,写起来确实比 ::: 啰嗦,这点和你体感一致。


03. 继续用 VitePress 语法,还是改写短代码?

推荐继续用 VitePress ::: 语法当作者接口。

理由:

  1. 你已经为它做了完整转换链,文档也按这个教读者写。
  2. 告警/折叠是写作语法,不是复杂组件;::: 更贴合 Markdown 心智。
  3. 短代码的「强大」主要体现在复杂交互组件上,用在 tip/warning 上是杀鸡用牛刀,还会拖累写作体验。
  4. 最终输出本来就会落到 custom-block / HTML,和手写短代码结果同类,只是入口更友好。
场景建议
tip / info / warning / danger / details继续写 :::
navCard、imgCard、code-group、复杂布局短代码或现有转换即可
想少依赖闭源 convert、追求纯 Hugo可逐步收敛,但不必为了告警先改掉

一句话:作者层保持 VitePress 简洁语法;Hugo 短代码当底层实现。 这正是 OneBlog 现在的设计,也更符合你的使用感受。

结束。

最新文章