Solitude Hugo Shortcode 使用指南

Shortcode 是 Hugo 在 Markdown 之外提供的内容组件语法。Solitude 用它承载提示框、标签页、图库、图表等富内容；迁移旧文章时，也应把 Hexo 外挂标签改写为对应的 Hugo shortcode。

开始之前

Hugo shortcode 有两种边界符：{{< shortcode >}} 适合普通参数，{{% shortcode %}} 会先处理内部 Markdown。Solitude 的块级组件已经按各自用途处理正文，通常直接使用尖括号写法即可。

内容类型	推荐组件	适合场景
行内强调	`span`、`label`、`keyboard`	一句话中的状态、术语或快捷键
块级提示	`note`、`subnote`、`fold`	说明、警告、补充资料
导航与引用	`button`、`link`、`card`	行动入口、站内外资源
结构化内容	`tabs`、`timeline`、`gallery`、`series`	分组、步骤、图片与文章集合
动态内容	`mermaid`、`chartjs`、`typeit`	流程、数据与动态文字

文本与状态

彩色文本与标签

p 用于整段文字，span 用于行内文字，label 用于短小的状态标记。颜色参数可使用 blue、green、orange、red、purple 等主题色名称。

写法

{{< p color="blue" >}}这是一段蓝色文字{{< /p >}}
正文中的 {{< span color="red" >}}重点文字{{< /span >}}
{{< label color="green" >}}已完成{{< /label >}}

效果

这是一段蓝色文字，用于在正文中形成较强的段落提示。

正文中的重点文字可以和普通内容自然排列。

已完成信息注意扩展

提示框

note 是主要提示组件，subnote 适合在一个主题下继续补充次级信息。

写法

{{< note type="info" style="flat" >}}
提示内容，支持 Markdown。
{{< /note >}}

{{< subnote type="warning" >}}次级提示{{< /subnote >}}

参数	是否必填	说明
`type`	否	`info`、`success`、`warning`、`danger`、`primary` 或默认样式
`style`	否	`flat`、`simple`、`modern`；默认使用 `flat`
正文	是	支持 Markdown 的提示内容

效果

选择、快捷键与隐藏文字

这组组件适合展示只读状态和行内补充信息。checkbox 与 radio 仅负责表达，不会提交表单。

{{< checkbox checked=true >}}已完成事项{{< /checkbox >}}
{{< radio checked=false >}}未选择事项{{< /radio >}}
{{< keyboard >}}⌘ K{{< /keyboard >}}
{{< spoiler >}}移入或聚焦后显示{{< /spoiler >}}
{{< bubble position="left" >}}气泡消息{{< /bubble >}}

已完成事项

尚未完成事项

已选择事项

新增检查项

按下 ⌘ K 打开搜索；答案是隐藏内容。气泡消息left

链接、按钮与媒体

按钮与链接卡片

button 提供主题按钮，并通过 option 组合颜色、描边和整行样式；link 将链接呈现为带说明的资源卡片。站外链接会自动在新窗口打开并附带安全属性。

写法

{{< button url="https://gohugo.io/" text="Hugo 官网" icon="fas fa-link" >}}
{{< button url="/" text="描边按钮" icon="fas fa-house" option="blue outline" >}}
{{< link url="/" title="站内链接" desc="返回示例站首页" >}}

参数	适用组件	说明
`url`	全部	目标地址
`text`	`button`	按钮文字
`icon`	`button`	图标类名
`option`	`button`	可组合 `outline`、颜色、`block` 等样式
`title` / `desc`	`link`	卡片标题与说明

效果

Hugo 官网描边按钮适合移动端换行的整行按钮

引用站外链接

Hugo

The world’s fastest framework for building websites

站内链接

站内链接与超长标题在窄屏下的截断和换行验证

返回示例站首页，检查移动端触控面积与键盘焦点状态。

图片

img 用于带说明的块级图片，inlineImg 用于跟随文字排列的小图片。

{{< img src="/img/default.avif" alt="示例图片" caption="主题默认封面" >}}
{{< inlineImg src="/img/logo.png" alt="Logo" height="24px" >}}

Solitude Shortcode 示例封面 — 本地 Shortcode 示例素材

Solitude 与 Hugo 可以出现在同一行文字中。

视频与音频

YouTube、哔哩哔哩、原生音频和原生视频分别使用独立组件。外部媒体是否可播放仍取决于来源站点、网络环境与浏览器策略。

{{< youtube id="dQw4w9WgXcQ" >}}
{{< bvideo bvid="BV1xx411c7mD" >}}
{{< audio url="/media/example.mp3" name="示例音频" >}}
{{< video url="/media/example.mp4" poster="/img/default.avif" >}}

折叠、隐藏与卡片

折叠面板

fold 使用原生 details 结构，支持鼠标、触摸和键盘操作。添加 open=true 可让内容默认展开。

{{< fold title="展开内容" open=true >}}
折叠区域内支持 **Markdown**。
{{< /fold >}}

展开内容

折叠区域内支持 Markdown。

默认展开的长标题折叠面板，用于检查移动端省略和多行正文布局

展开状态同样使用柔和表面、清晰分隔和可见的键盘焦点，不依赖鼠标悬停。

点击后显示

三个隐藏组件的区别只在呈现方式：hideInline 适合一句话，hideBlock 适合独立内容块，hideToggle 适合带标题的可切换区域。

{{< hideInline text="查看答案" >}}答案{{< /hideInline >}}
{{< hideBlock text="展开内容" >}}块级内容{{< /hideBlock >}}
{{< hideToggle title="阅读更多" >}}可切换内容{{< /hideToggle >}}

哪个组件适合藏在一句话里？

内容卡片

card 用于推荐项目、文章或资源。封面是可选项，没有封面时会自动切换到纯内容布局。

{{< card title="Hugo 卡片" url="https://gohugo.io/"
    cover="/img/default.avif" tag="资源" star="5" >}}
卡片说明
{{< /card >}}

参数	说明
`title`	卡片标题，也可使用 `name`
`url`	可选的跳转地址
`cover`	可选封面，也可使用 `bg`
`tag` / `star`	分类标签与评分
`width` / `height`	可选尺寸，建议优先沿用默认响应式宽度

封面卡片

Hugo 卡片展示主题与重点内容

纯内容

无封面卡片简洁，也保持完整层级

数据与可视化

Mermaid 流程图

mermaid 直接接收 Mermaid 语法，适合流程图、时序图、状态图等结构化图形。

{{< mermaid >}}
flowchart LR
  Hexo --> Hugo
  Hugo --> HTML
{{< /mermaid >}}

flowchart LR Hexo --> Hugo Hugo --> HTML

Chart.js 图表

chartjs 支持 id、layout、width 和 description 参数。正文必须是合法 JSON。

{{< chartjs description="三期构建趋势" >}}
{"type":"line","data":{"labels":["一","二","三"],"datasets":[{"label":"趋势","data":[1,3,2]}]}}
{{< /chartjs >}}

{"type":"line","data":{"labels":["一","二","三"],"datasets":[{"label":"趋势","data":[1,3,2]}]}}

三期构建趋势

乐谱与动态文字

score 使用 ABC 记谱文本，typeit 用 speed 控制逐字显示速度。

{{< typeit speed="60" >}}TypeIt 动态文本{{< /typeit >}}

X:1 T:Hugo migration M:4/4 K:C C D E F|G A B c|

TypeIt 动态文本

仓库与站点资源

仓库卡片

四个仓库组件使用同样的 repo="组织/仓库" 写法；自建 Gitea 还需要提供 host。仓库数据由浏览器访问对应平台 API，因此加载状态可能受网络或频率限制影响。

{{< github repo="gohugoio/hugo" >}}
{{< gitlab repo="gitlab-org/gitlab" >}}
{{< gitee repo="mirrors/hugo" >}}
{{< gitea repo="go-gitea/gitea" host="https://gitea.com" >}}

GitHub

hugo

正在读取仓库信息…

——

加载中

GitLab

gitlab

正在读取仓库信息…

——

加载中

Gitee

hugo

正在读取仓库信息…

——

加载中

Gitea

gitea

正在读取仓库信息…

——

加载中

友链列表

flink 的正文是 YAML 数据。一个组件可以包含多个分组，每个分组下可以继续放置多个站点。

{{< flink >}}
- class_name: 官方资源
  class_desc: Hugo 官方网站
  link_list:
    - name: Hugo
      link: https://gohugo.io/
      avatar: https://gohugo.io/images/hugo-logo-wide.svg
      descr: 世界上最快的网站构建框架
{{< /flink >}}

官方资源

Hugo 官方网站

Hugo 世界上最快的网站构建框架

布局与内容集合

图库与图库分组

gallery 负责瀑布流容器，内部使用 galleryItem 放置不同宽高的图片；columns 可指定桌面端列数。galleryGroup 则用于创建带封面、说明和链接的图库入口。

{{< gallery columns="2" >}}
{{< galleryItem src="/img/default.avif" alt="Gallery 1" >}}
{{< galleryItem src="/img/default.avif" alt="Gallery 2" >}}
{{< galleryItem src="/img/default.avif" alt="Gallery 3" >}}
{{< galleryItem src="/img/default.avif" alt="Gallery 4" >}}
{{< /gallery >}}

Group Image Gallery — 图库分组
用于聚合同一主题下的一组图片。

标签页

tabs 作为容器，每个 tab 提供标题和内容。为同一篇文章里的每组标签页设置唯一 id，可以避免状态互相影响。

{{< tabs id="demo-tabs" >}}
{{< tab title="第一个" >}}第一个标签页{{< /tab >}}
{{< tab title="第二个" >}}第二个标签页{{< /tab >}}
{{< /tabs >}}

第一个标签页

第二个标签页

窄屏下标签导航可以横向滚动，并保留完整的键盘操作。

时间线

时间线由 timeline 和一个或多个 timenode 组成。时间与标题应保持简短，详细说明放在节点正文中。

{{< timeline title="迁移时间线" >}}
{{< timenode time="2026-08-21" title="Hugo 版本" >}}
完成原生主题迁移。
{{< /timenode >}}
{{< /timeline >}}

迁移时间线

2026-08-21

Hugo 版本完成原生主题迁移。

2026-08-25

文档重组补充写法、参数与真实效果，让组件更容易检索和复用。

系列文章与视频集合

series 会读取文章 Front Matter 中同名的 series，并按日期生成文章列表。videos 则把正文中的每行地址渲染为一个原生视频播放器。

{{< series name="官方示例" >}}

{{< videos col="2" >}}
/media/shortcodes/flower.mp4
/media/shortcodes/friday.mp4
{{< /videos >}}

使用建议

先用标准 Markdown 完成正文，只在标准语法无法表达时引入 shortcode。
一个组件解决一种内容关系，避免为了装饰而层层嵌套。
图片和媒体补全替代文本或标题，并优先选择稳定、可控的资源地址。
发布前执行完整构建，再在桌面端与移动端检查长标题、代码块、表格和交互组件。