短代码(shortcode)

短代码是 Hugo 提供的模板化片段,可以在 Markdown 里直接调用。

参考:https://stack.jimmycai.com/writing/shortcodes

视频插入

{{< youtube VIDEO_ID >}}
{{< bilibili VIDEO_ID PART_NUMBER >}}
{{< tencent VIDEO_ID >}}
  • youtube 的参数是视频 ID,例如 https://www.youtube.com/watch?v=ZFL09qhKi5I 里的 ZFL09qhKi5I
  • bilibili 的第一个参数是 BV 号或 av 号,第二个参数是分 P,省略时默认第 1 P
  • tencent 的参数是腾讯视频的 vid

如果页面在国内访问,YouTube 的 iframe 可能加载不出来;这种情况下换成 bilibili 短代码更稳。

图标插入

iconify

把 iconify-icon.min.js 放到 assets/plugins/iconify/ 下,然后在 config.toml 里注册:

[[params.plugins.js]]
link = "plugins/iconify/iconify-icon.min.js"

之后可以在 Markdown 里直接使用:

<iconify-icon icon="simple-icons:bilibili"></iconify-icon>

icons8 / Line Awesome

在 config.toml 里配置社交图标:

[[params.social]]
icon = "lab la-github" # https://icons8.com/line-awesome
url = "https://github.com/podcast-of-engineers"

模板里这样渲染:

<li class="list-inline-item">
    <a href="{{ .link | safeURL }}">
        <i class="lab {{ .icon }}"></i>
    </a>
</li>

lab 是 Line Awesome 的样式前缀,la- 后面接具体图标名;lab 通常表示品牌图标(brand)。

面包屑(breadcrumb)

面包屑用于显示当前页面在站点层级中的位置,例如「首页 / 博客 / 文章标题」。Hugo 本身不限制实现方式,常见做法是在 layouts/partials/ 下写一个模板,按 .Parent、.Section、.CurrentSection 逐级往上找:

<nav aria-label="breadcrumb">
  <ol>
    <li><a href="{{ "/" | relURL }}">首页</a></li>
    {{ with .CurrentSection }}
      <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
    {{ end }}
    <li aria-current="page">{{ .Title }}</li>
  </ol>
</nav>

然后在文章模板里 {{ partial "breadcrumb.html" . }}。

Hugo 的目录结构

my-site/
├── archetypes/     # hugo new 使用的模板
├── assets/         # 需要 Hugo Pipes 处理的文件
├── config.toml     # 站点配置(新版本叫 hugo.toml)
├── content/        # 文章内容
├── data/           # 数据文件(YAML/JSON/TOML)
├── layouts/        # 模板
├── public/         # 构建输出
├── static/         # 原样复制的静态文件
└── themes/         # 主题
  • archetype:hugo new 的模板
  • assets:需要用 Hugo Pipes 处理的文件(SCSS、JS、图片等)
  • config:个性化设置
  • content:hugo new 出来文件的默认位置;子文件夹里有 _index.md 时会成为 section
  • data:模板里用 .Site.Data 读取的数据
  • layouts:覆盖主题模板时放在这里
  • static:构建时原样复制到 public/,不经过模板处理
  • themes:主题目录,通常用 git submodule 管理

参考:https://gohugo.io/getting-started/directory-structure/

视频示例