笔记：Hugo 中 Shortcode 的基本使用

起因

Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video ) to Markdown content. We think this contradicts the beautiful simplicity of Markdown’s syntax.

Hugo created Shortcodes to circumvent these limitations.

– 《What a Shortcode is》

使用到 Shortcode，是博客迁移过程中的历史遗留问题。 博客中有不少自定义的样式，甚至有时候在写一篇笔记的时候直接在 markdown 文件里直接通过行内 <style/> 标签写一些想要的样式，例子是下面这几个不同颜色背景的区块：

使用 Jekyll 的时候，借助其 markdown 语法渲染引擎 kramdown 的帮助，这些不同背景颜色的 <div/>，要使其标签里的内容也可以获得 markdown 渲染，只需要在元素标签加上 markdown="1" 这个属性¹。

但 markdown 的标准中不允许 HTML 元素和 markdown 内容共存，所以 Hugo 的 markdown 语法解析器 BlackFriday 并没有对 markdown="1" 这个属性作支持，也没有找到其它类似的属性可以达到需要的效果。最后在社区里找到利用 Shortcode 来达到效果的办法²。

基本使用

从基本的创建开始。首先在声明每一个 Shortcode 的时候，都需要在 ./layouts 目录下的同名目录（./Shortcodes） 下来创建对应的文件，结合自己使用感受，其实可以把 Shortcode 理解成 Hugo 视图渲染里的 template in template。

以将 <div/> 之中的内容获得 markdown 渲染这一基础需求为例：

1. 创建 ./layouts/Shortcodes/md.html；
2. 在上一步创建的 ./layouts/Shortcodes/md.html 中输入 {{ .Inner }}。

之后在 html 中就可以通过一下片段来使 html 标签中的 markdown 生效：

但 Shortcode 的用法不止于此，本小节开头那几个作为例子、不同背景颜色区块使用的是同一个 Shortcode，被我命名为 section.html，通过传参的方式在不同时候调用不同的 class 已达到不同的区块显示效果：

比如我想建立一个 class="warning" 的区块，在 .md 中输入如下片段就可以调用：

效果：

除了 section.html 之外，本地还做了更好展示图片和 CodePen 的两个 Shortcode，展示图片的如下：

官方文档上也给出了相当多例子，比如图片墙，Shortcode 的相互嵌套，具体请阅读《Custom Shortcode Examples》