# 手把手教程：怎么让 Hugo shortcode 只显示代码，而不是被直接解析执行 {{< music auto="https://music.163.com/#/playlist?id=12472829847" >}} 有些坑，第一次踩进去的时候，真的会让人怀疑人生。😅 明明只是想在文章里展示一段 Hugo shortcode 源码，结果一保存、一刷新，代码没显示出来，页面反而把它执行了，图片也真的渲染出来了。那一刻你会很懵：我不是已经放进代码块了吗，为什么它还是不听话？ 后来我才真正搞明白：这类问题最怕的，不是不会写，而是以为“代码块已经足够安全”。实际上，在 Hugo 这里，光有代码块还不够。你还得避免让正文里出现会被 Hugo 识别成真实 shortcode 的原始写法。 这次我干脆把最稳、最不容易再炸构建的方法整理成一篇能直接照着做的版本。它不是“理论上可行”，而是专门冲着“别再报错了”去的。🛠️ *** ## 一、问题到底出在哪？ 🤔 你本来想展示的是这样一段 shortcode： **注意这里我把原本的 `{{` 和 `}}`，替换成了的 `【【` 和 `】】`代替，否则无法构建成功。** 这就是我们要解决的问题。 ````text [[< style ".rounded-img img { border-radius: 8px; }" >]] [[< image src="/images/post-end/night-rain-lamp-1200.webp" alt="文尾配图水墨画图片" src_s="/images/post-end/night-rain-lamp-800.webp" src_l="/images/post-end/night-rain-lamp-1600.webp" width="100%" class="rounded-img" >]] [[< /style >]] ```` 但只要这段原始 shortcode 真的出现在文章正文里，Hugo 就有机会先把它当成要执行的东西去解析，而不是当成普通文字展示出来。 一旦它开始解析，像 `.rounded-img img { border-radius: 8px; }` 这种带点号和 CSS 内容的参数，就很容易触发你看到的那种报错： ```text unrecognized character in shortcode action: U+002E '.' ``` 所以，真正的问题不是“你不会写代码块”，而是**文章里仍然出现了 Hugo 眼中的原始 shortcode 语法**。⚠️ *** ## 二、这次我给你的，是绝对更稳的写法 ✅ 为了彻底避开构建报错，这篇文章里我不再直接放原始的 shortcode 语法，也不依赖 Hugo 自己的 shortcode 转义机制来赌环境差异。 我给你的方案是： - 文章里展示时，用“占位符写法”显示源码； - 读者复制后，再手动替换回真正的 `｛｛< ... >｝｝`； - 这样 Hugo 在构建时根本看不到可执行 shortcode，自然也就不会再炸。🧯 换句话说，这不是最“优雅”的教程展示法，但它是当前最“稳”的发布法。 *** ## 三、最安全的展示方式：用占位符代替大括号 ✍️ 下面这段，就是我建议你在文章里直接展示给读者看的版本： ````markdown ```markdown 【【< style ".rounded-img img { border-radius: 8px; }" >】】 【【< image src="/images/post-end/night-rain-lamp-1200.webp" alt="文尾配图水墨画图片" src_s="/images/post-end/night-rain-lamp-800.webp" src_l="/images/post-end/night-rain-lamp-1600.webp" width="100%" class="rounded-img" >】】 【【< /style >】】 ``` ```` 这里我把原本的 `{{` 和 `}}`，替换成了更安全的 `【【` 和 `】】`。这样做的好处非常直接： - Hugo 不会把它识别成 shortcode； - 页面能正常显示代码； - 读者也能一眼看懂该替换哪里； - 最重要的是，构建更稳，不容易再冒出奇怪报错。🙂 *** ## 四、读者复制后怎么恢复成真正可执行代码？ 🔧 你可以在代码块下面直接补一句说明： > 使用时，把所有 `【【` 替换成“双左花括号”，再把所有 `】】` 替换成“双右花括号”，就能恢复成真正可执行的 Hugo shortcode。 也就是说，上面那段占位符代码，恢复后就是： ````text 【【< style ".rounded-img img { border-radius: 8px; }" >】】 【【< image src="/images/post-end/night-rain-lamp-1200.webp" alt="文尾配图水墨画图片" src_s="/images/post-end/night-rain-lamp-800.webp" src_l="/images/post-end/night-rain-lamp-1600.webp" width="100%" class="rounded-img" >】】 【【< /style >】】 ```` 注意：上面这一段只是说明效果，所以我放在普通文本代码块里；你不要再把它原样塞回文章正文里展示，否则又会回到老问题。😅 *** ## 五、为什么我这次不继续让你用 shortcode 转义写法？ 🌧️ 理论上，Hugo 的确支持用转义方式来展示 shortcode 源码。 *** > **关于用 Hugo 的 shortcode 转义写法：** 也就是在 shortcode 定界符里加 /* 和 */，这样它就会显示成代码，而不会被执行。 核心规则是：把原来的 {删这字{< ... >}} 改成 {删这字{}}，闭合标签 {删这字{< /style >}} 也同样改成 {删这字{}}。 这是 Hugo 官方社区和相关文档里推荐的 shortcode 转义方式，专门用来在 Markdown 里展示 shortcode 源码示例。 ```markdown {{}} {{}} {{}} ``` 如果你只是单行 shortcode，也同样这样处理，例如： ```markdown {{}} ``` 之前明明放在代码块里却还是被解析，是因为 Hugo 在某些 Markdown 渲染场景下，即使在 fenced code block 里也可能继续处理 shortcode，所以只靠三个反引号并不总是够用。 最稳妥的办法就是：代码块 + shortcode 转义 一起用。 *** 但这次你的实际情况已经说明了一件事：**你现在更需要的是能稳定构建成功的文件，而不是继续赌不同环境下的解析细节。** 尤其当文章里同时出现： - Markdown 代码块； - 多行 shortcode； - 带引号的字符串参数； - 带点号和花括号的 CSS 片段； 这时候，最保险的办法就是直接绕开 Hugo 对 shortcode 语法的识别入口。占位符法虽然笨一点，但稳。对博客发布来说，稳往往比“看起来更高级”更重要。🕯️ *** ## 六、手把手操作：你现在到底该怎么写？ 🛠️ 如果你想以后每次写 Hugo 教程都不再被这个问题折腾，可以直接按这个流程走。 ### 第一步：把你想展示的原始 shortcode 先写出来 例如原始代码是： ````text {删这字{< image src="/images/demo.webp" alt="示例图片" width="100%" >}} ```` ### 第二步：把外层大括号换成占位符 改成： ````text 【【< image src="/images/demo.webp" alt="示例图片" width="100%" >】】 ```` ### 第三步：再放进 Markdown 代码块里展示 ````markdown ```markdown 【【< image src="/images/demo.webp" alt="示例图片" width="100%" >】】 ``` ```` ### 第四步：在代码块下面补一句使用说明 比如： > 复制后，把 `【【` 改成双左花括号，把 `】】` 改成双右花括号，再粘贴到正文里执行。 到这里，这篇教程就既能正常显示，又不容易再把站点构建搞炸。 *** ## 七、你的这段代码，我帮你改成最终可展示版 📌 你这次最开始那段代码，最终适合放在文章里的版本，我再完整给你放一次： ````markdown ```markdown 【【< style ".rounded-img img { border-radius: 8px; }" >】】 【【< image src="/images/post-end/night-rain-lamp-1200.webp" alt="文尾配图水墨画图片" src_s="/images/post-end/night-rain-lamp-800.webp" src_l="/images/post-end/night-rain-lamp-1600.webp" width="100%" class="rounded-img" >】】 【【< /style >】】 ``` ```` 下面再加一句： > 真正使用时，请把 `【【` 改回 `{{`，把 `】】` 改回 `}}`。 这样就够了。不要再在同一篇文章里额外放一段真的 `｛｛< style ... >｝｝` 当“实际使用版”，不然很容易再次触发解析。🚫 *** ## 八、如果是单行 shortcode，也完全一样 ✨ 比如你只想展示这一行： ````text ｛｛< image src="/images/post-end/night-rain-lamp-1200.webp" alt="文尾配图水墨画图片" width="100%" >｝｝ ```` 那文章里安全展示版就写成： ````markdown ```markdown 【【< image src="/images/post-end/night-rain-lamp-1200.webp" alt="文尾配图水墨画图片" width="100%" >】】 ``` ```` 规则完全一样，不需要另学一套。 *** ## 九、写在最后 🌌 我越来越觉得，很多技术问题最折磨人的地方，不是它有多难，而是它总把人困在那种“明明快对了，为什么又错了”的来回拉扯里。 你改一遍，刷一遍，再改一遍，再刷一遍。最后消耗掉的往往不只是时间，还有注意力、耐心，以及那一点原本不该浪费的心气。 所以这次我不再给你“理论上更优雅但环境里未必最稳”的版本，而是直接给你一份更适合发出去、也更不容易报错的发布版。它可能不炫，但足够可靠。 如果这篇文章刚好帮你少掉一次无效折腾，那它就已经值了。🤝 *** --全文完-- 感谢阅读 *** > **“同频之人，终会相遇；同行之路，终有光亮。”** {{< typeit tag=h4 >}} **“愿与身处同境、灵魂同频、砥砺前行的你相遇相伴，倾听彼此的故事与困惑，分享心路与感悟，在逆境中自救破局的路上彼此陪伴、相互照亮、同行向前,一起走向重生与新生。”**... {{< /typeit >}} {{< admonition type=question title="若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊：" open=true >}} > **微信公众号：** 梦行志微信公众号 > **私人微信号(有验证)：oklife_1314** 梦行志个人微信二维码 > **我的邮箱📫：** > {{< /admonition >}} *** {{< admonition type=success title="希望我写的每一个字，成为我自己和某个人活下去、拼下去的力量。" open=true >}} “技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。” 本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明来自https://oklife.me。 文尾配图水墨画图片 {{< /admonition >}}