# Shortcodes：Hugo 内置 本文列出了 Hugo 提供的内置 Shortcodes 功能语法，可以在扩展 Markdown 渲染格式的同时保持内容简洁。 ## 简介 Markdown 因其简洁的内容格式而备受亲赖，但就搭建网站页面内容而言，其支持的渲染格式多少有些捉襟见肘。因此，内容创作者们往往不得不在简洁的 Markdown 文档中插入原始 HTML 标签（例如视频 `` 标签），这严重破坏了 Markdown 文档简洁、优雅的美感。 对此，Hugo 作为一个静态网站生成器，提出 Shortcodes 功能语法来规避上述 Markdown 语法的局限性。[Shortcodes](https://gohugo.io/content-management/shortcodes/) 是可以在 Markdown 内容文件中轻松使用的、简短的代码片段，Hugo 在构建网站页面时会按照预先定义好的 HTML 模版来渲染这些代码片段。 这种将文档内容与 HTML 渲染过程分离的设计思路很好的延续了 Markdown 的设计哲学。当我们更新 Shortcodes 中涉及或使用的 HTML 类、技术或标准后，Hugo 会在渲染过程中自动应用这些修改和更新。因此，使用 Shortcodes 除了可以维持 Markdown 文档的简洁外，还免除了因更新 HTML 框架而带来的繁杂的搜索和替换操作。 ## 使用 Shortcodes 的使用格式一般为： `{{%/* shortcode-name parameter1="value1" parameter2="value2" ... */%}}` + Shortcodes 的界定符号有两种： + `{{%/* ... */%}}`：`...` 中的内容（如 Markdown 语法等）会被 Hugo 渲染为 HTML。 + `{{}}`：`...` 中的内容（一般为 HTML 代码）不会被 Hugo 再次渲染。 + Shortcodes 的界定方式同 HTML 中的标签，也有两种： + 单独：`{{%/* shortcode-name parameters ... */%}}` + 成对：`{{%/* shortcode-name parameters */%}} ... {{%/* /shortcode-name */%}}` + `shortcode-name` 为 Shortcades 的名称，必须位于开头。其后为 Shortcodes 传递的参数列表。 + 根据 Shortcodes 的具体定义，其参数有两种传递方式： + 按参数名传递：`parameter1="value1" parameter2="value2" ...` + 按位置顺序传递：`value1 value2 ... ` + `...` 多行内容需使用原始字符串形式，如： ```Markdown {linenos=false} {{HTML, and a new line with a "quoted sting".` */>}} ``` {{% admonition info "参考" %}} Hugo 内置 Shortcodes 的详细介绍以及示例请参考 [Hugo 文档 - Shortcodes ](https://gohugo.io/content-management/shortcodes/#highlight)。 {{% /admonition %}} ## figure `figure` 拓展了 Markdown 中的 image 语法，支持 HTML5 `
` 元素。 ```Markdown {{}} ``` ```HTML
alt of image

Title of image

Caption of image Attr of image

``` **呈现的效果：** {{< figure src = "/images/WingsofLiberty.webp" link = "https://www.newverse.wiki/" target = "_blank" rel = "nofollow noopener noreferrer" alt = "alt of image" caption = "**Caption** of image" title = "Title of image" class = "figure image" height = "400" width = "400" loading = "lazy" attr = "**Attr** of image" attrlink = "https://www.newverse.wiki/" >}} ## gist 用于在网页中插入 [GitHub gist](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists) 代码片段。 ```Markdown {{}} ``` ```HTML ``` **呈现的效果：** {{< gist spf13 7896402 >}} ## highlight 用于在网页中插入带语法高亮的代码片段。 {{% admonition info "参考" %}} 可选的高亮参数请参考 [Hugo 文档 - Highlight 函数](https://gohugo.io/functions/transform/highlight/)。 {{% /admonition %}} ```Markdown {{}}

{{ .Title }}

{{ range .Pages }} {{ .Render "summary"}} {{ end }}
{{}} ``` **呈现的效果：** {{< highlight html "lineNos=table, hl_Lines=1 3-6, lineNoStart=42" >}}

{{ .Title }}

{{ range .Pages }} {{ .Render "summary"}} {{ end }}
{{< /highlight >}} ## param 获取当前页面中前置参数（front matter）的值，若当前页面中未设置该前置参数则获取网站配置 `hugo.toml` 中相应参数的值，若网站配置文件中也未找到相应参数，则返回 `ERROR`。 如获取当前页面的标题： ```Markdown {{%/* param title */%}} ``` **呈现的效果：** {{% param title %}} ## ref 与 relref 在制作站内超链接时，按照给定的其相对路径（例如 `blog/post.md`）或逻辑名称（`post.md`），查找并返回所找到页面的链接（ref）或相对链接（relref）。 ```Markdown [Markdown 基本语法]({{}}) [Markdown 扩展语法]({{}}) ``` ```HTML Markdown 基本语法 Markdown 扩展语法 ``` **呈现的效果：** [Markdown 基本语法]({{< ref "/senses/MarkdownBasics.md" >}}) [Markdown 扩展语法]({{< relref "MarkdownExtended.md#emoji" >}}) ## tweet 用于在网页中插入 Twitter 展示页面。 ```Markdown {{}} ``` ```HTML ``` **呈现的效果：** {{< admonition bug >}} 无法加载 twitter 展示页面 {{< /admonition >}} ## vimeo 用于在网页中插入 vimeo 视频。 ```Markdown {{}} 或者 {{}} ``` ```HTML
``` **呈现的效果：** {{< vimeo 55073825 >}} ## youtube 用于在网页中插入 YouTube 视频。 ```Markdown {{}} 或者 {{}} ``` ```HTML
``` **呈现的效果：** {{< youtube id="w7Ft2ymGmfc" autoplay="false" title="A New Hugo Site in Under Two Minutes" >}} *** 【参考】 + [Hugo 文档 - Shortcodes](https://gohugo.io/content-management/shortcodes/#highlight) --- > 作者: [XOlDKING](https://www.newverse.wiki) > URL: https://www.newverse.wiki/senses/shortcodesbuiltin/