Hugo文档 - 5. Shortcodes

wiz 收录于分类 Documentation

2019-03-17 2021-11-17 约 3181 字预计阅读 7 分钟

Hugo 提供了多个内置的 Shortcodes , 以方便作者保持 Markdown 内容的整洁.

内置shortcodes

Hugo 使用 Markdown 为其简单的内容格式. 但是, Markdown 在很多方面都无法很好地支持. 你可以使用纯 HTML 来扩展可能性.

但这恰好是一个坏主意. 大家使用 Markdown, 正是因为它即使不经过渲染也可以轻松阅读. 应该尽可能避免使用 HTML 以保持内容简洁.

为了避免这种限制, Hugo 创建了 shortcodes. shortcode 是一个简单代码段, 可以生成合理的 HTML 代码, 并且符合 Markdown 的设计哲学.

Hugo 附带了一组预定义的 shortcodes, 它们实现了一些非常常见的用法. 提供这些 shortcodes 是为了方便保持你的 Markdown 内容简洁.

figure

figure 的文档

一个 figure 示例:

1

{{< figure src="https://pic.imgdb.cn/item/629a49d0094754312954f801.png" title="Hugo" >}}

呈现的输出效果如下:

输出的 HTML 看起来像这样:

1
2
3
4
5
6


<figure>
    <img src="https://pic.imgdb.cn/item/629a49d0094754312954f801.png"/>
    <figcaption>
        <h4>Hugo</h4>
    </figcaption>
</figure>

highlight

highlight 的文档

一个 highlight 示例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{{< highlight html >}}
<section id="main">
    <div>
        <h1 id="title">{{ .Title }}</h1>
        {{ range .Pages }}
            {{ .Render "summary"}}
        {{ end }}
    </div>
</section>
{{< /highlight >}}

呈现的输出效果如下:

1
2
3
4
5
6
7
8


<section id="main">
    <div>
        <h1 id="title">{{ .Title }}</h1>
        {{ range .Pages }}
            {{ .Render "summary"}}
        {{ end }}
    </div>
</section>

扩展shortcodes

link

link shortcode 是 Markdown 链接语法的替代. link shortcode 可以提供一些其它的功能并且可以在代码块中使用.

支持本地资源引用的完整用法.

link shortcode 有以下命名参数:

href [必需] (第一个位置参数)

链接的目标.
content [可选] (第二个位置参数)

链接的内容, 默认值是 href 参数的值.

支持 Markdown 或者 HTML 格式.
title [可选] (第三个位置参数)

HTML a 标签的 title 属性, 当悬停在链接上会显示的提示.
rel [可选]

HTML a 标签的 rel 补充属性.
class [可选]

HTML a 标签的 class 属性.

一个 link 示例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{{< link "https://assemble.io" >}}
或者
{{< link href="https://assemble.io" >}}

{{< link "mailto:contact@revolunet.com" >}}
或者
{{< link href="mailto:contact@revolunet.com" >}}

{{< link "https://assemble.io" Assemble >}}
或者
{{< link href="https://assemble.io" content=Assemble >}}

呈现的输出效果如下:

一个带有标题的 link 示例:

1
2
3


{{< link "https://github.com/upstage/" Upstage "Visit Upstage!" >}}
或者
{{< link href="https://github.com/upstage/" content=Upstage title="Visit Upstage!" >}}

呈现的输出效果如下 (将鼠标悬停在链接上, 会有一行提示):

Upstage

image

image shortcode 是 figure shortcode 的替代. image shortcode 可以充分利用 lazysizes 和 lightgallery.js 两个依赖库.

支持本地资源引用的完整用法.

image shortcode 有以下命名参数:

src [必需] (第一个位置参数)

图片的 URL.
alt [可选] (第二个位置参数)

图片无法显示时的替代文本, 默认值是 src 参数的值.

支持 Markdown 或者 HTML 格式.
caption [可选] (第三个位置参数)

图片标题.

支持 Markdown 或者 HTML 格式.
title [可选]

当悬停在图片上会显示的提示.
class [可选]

HTML figure 标签的 class 属性.
src_s [可选]

图片缩略图的 URL, 用在画廊模式中, 默认值是 src 参数的值.
src_l [可选]

高清图片的 URL, 用在画廊模式中, 默认值是 src 参数的值.
height [可选]

图片的 height 属性.
width [可选]

图片的 width 属性.
linked [可选]

图片是否需要被链接, 默认值是 true.
rel [可选]

HTML a 标签的 rel 补充属性, 仅在 linked 属性设置成 true 时有效.

一个 image 示例:

1

{{< image src="/images/lighthouse.webp" caption="Lighthouse (`image`)" src_s="/images/lighthouse-small.webp" src_l="/images/lighthouse-large.webp" >}}

呈现的输出效果如下:

/images/lighthouse.webp — Lighthouse (`image`)

admonition

admonition shortcode 支持 12 种帮助你在页面中插入提示的横幅.

支持 Markdown 或者 HTML 格式.

注意

一个注意横幅

摘要

一个摘要横幅

信息

一个信息横幅

技巧

一个技巧横幅

成功

一个成功横幅

问题

一个问题横幅

警告

一个警告横幅

失败

一个失败横幅

危险

一个危险横幅

Bug

一个 Bug 横幅

示例

一个示例横幅

引用

一个引用横幅

admonition shortcode 有以下命名参数:

type [必需] (第一个位置参数)

admonition 横幅的类型, 默认值是 note.
title [可选] (第二个位置参数)

admonition 横幅的标题, 默认值是 type 参数的值.
open [可选] (第三个位置参数)

一个 admonition 示例:

1
2
3
4
5
6
7


{{< admonition type=tip title="This is a tip" open=false >}}
一个 **技巧** 横幅
{{< /admonition >}}
或者
{{< admonition tip "This is a tip" false >}}
一个 **技巧** 横幅
{{< /admonition >}}

呈现的输出效果如下:

This is a tip

一个技巧横幅

music

music shortcode 基于 APlayer 和 MetingJS 提供了一个内嵌的响应式音乐播放器.

有三种方式使用 music shortcode.

自定义音乐 URL

支持本地资源引用的完整用法.

music shortcode 有以下命名参数来使用自定义音乐 URL:

server [必需]

音乐的链接.
type [可选]

音乐的名称.
artist [可选]

音乐的创作者.
cover [可选]

音乐的封面链接.

一个使用自定义音乐 URL 的 music 示例:

1

{{< music url="/music/Wavelength.mp3" name=Wavelength artist=oldmanyoung cover="/images/Wavelength.webp" >}}

呈现的输出效果如下:

音乐平台 URL 的自动识别

music shortcode 有一个命名参数来使用音乐平台 URL 的自动识别:

auto [必需]] (第一个位置参数)

用来自动识别的音乐平台 URL, 支持 netease, tencent 和 xiami 平台.

一个使用音乐平台 URL 的自动识别的 music 示例:

1
2
3


{{< music auto="https://music.163.com/#/playlist?id=60198" >}}
或者
{{< music "https://music.163.com/#/playlist?id=60198" >}}

呈现的输出效果如下:

自定义音乐平台, 类型和 ID

music shortcode 有以下命名参数来使用自定义音乐平台:

server [必需] (第一个位置参数)

[netease, tencent, kugou, xiami, baidu]

音乐平台.
type [必需] (第二个位置参数)

[song, playlist, album, search, artist]

音乐类型.
id [必需] (第三个位置参数)

歌曲 ID, 或者播放列表 ID, 或者专辑 ID, 或者搜索关键词, 或者创作者 ID.

一个使用自定义音乐平台的 music 示例:

1
2
3


{{< music server="netease" type="song" id="1868553" >}}
或者
{{< music netease song 1868553 >}}

呈现的输出效果如下:

其它参数

music shortcode 有一些可以应用于以上三种方式的其它命名参数:

theme [可选]

音乐播放器的主题色, 默认值是 #448aff.
fixed [可选]

是否开启固定模式, 默认值是 false.
mini [可选]

是否开启迷你模式, 默认值是 false.
autoplay [可选]

是否自动播放音乐, 默认值是 false.
volume [可选]

第一次打开播放器时的默认音量, 会被保存在浏览器缓存中, 默认值是 0.7.
mutex [可选]

是否自动暂停其它播放器, 默认值是 true.

music shortcode 还有一些只适用于音乐列表方式的其它命名参数:

loop [可选]

[all, one, none]

音乐列表的循环模式, 默认值是 none.
order [可选]

[list, random]

音乐列表的播放顺序, 默认值是 list.
list-folded [可选]

初次打开的时候音乐列表是否折叠, 默认值是 false.
list-max-height [可选]

音乐列表的最大高度, 默认值是 340px.

bilibili

bilibili shortcode 提供了一个内嵌的用来播放 bilibili 视频的响应式播放器.

如果视频只有一个部分, 则仅需要视频的 BV id, 例如:

1

https://www.bilibili.com/video/BV1zJ411E7J9

一个 bilibili 示例:

1
2
3


{{< bilibili BV1zJ411E7J9 >}}
或者
{{< bilibili id=BV1zJ411E7J9 >}}

呈现的输出效果如下:

如果视频包含多个部分, 则除了视频的 BV id 之外, 还需要 p, 默认值为 1, 例如:

1

https://www.bilibili.com/video/BV1TJ411C7An?p=3

一个带有 p 参数的 bilibili 示例:

1
2
3


{{< bilibili BV1TJ411C7An 3 >}}
或者
{{< bilibili id=BV1TJ411C7An p=3 >}}

呈现的输出效果如下:

typeit

typeit shortcode 基于 TypeIt 提供了打字动画.

只需将你需要打字动画的内容插入 typeit shortcode 中即可.

简单内容

允许使用 Markdown 格式的简单内容, 并且 不包含 富文本的块内容, 例如图像等等…

一个 typeit 示例:

1

{{< typeit >}}这一个带有基于 [TypeIt](https://typeitjs.com/) 的 **打字动画** 的 *段落*...{{< /typeit >}}

呈现的输出效果如下:

另外, 你也可以自定义 HTML 标签.

一个带有 h4 标签的 typeit 示例:

1

{{< typeit tag=h4 >}}这一个带有基于 [TypeIt](https://typeitjs.com/) 的 **打字动画** 的 *段落*...{{< /typeit >}}

呈现的输出效果如下:

代码内容

代码内容也是允许的, 并且通过使用参数 code 指定语言类型可以实习语法高亮.

一个带有 code 参数的 typeit 示例:

1
2
3
4
5
6
7


{{< typeit code=java >}}
public class HelloWorld {
    public static void main(String []args) {
        System.out.println("Hello World");
    }
}
{{< /typeit >}}

呈现的输出效果如下:

分组内容

默认情况下, 所有打字动画都是同时开始的. 但是有时你可能需要按顺序开始一组 typeit 内容的打字动画.

一组具有相同 group 参数值的 typeit 内容将按顺序开始打字动画.

一个带有 group 参数的 typeit 示例:

1
2
3
4
5
6
7


{{< typeit group=paragraph >}}
**首先**, 这个段落开始
{{< /typeit >}}

{{< typeit group=paragraph >}}
**然后**, 这个段落开始
{{< /typeit >}}

呈现的输出效果如下:

friend

friend shortcode 用来在你的页面上插入友链.

friend shortcode 有以下命名参数:

name [必需] (第一个位置参数)

友站的名称.
url [必需] (第二个位置参数)

友站的链接.
avatar [必需] (第三个位置参数)

友站的头像.
bio [必需] (第四个位置参数)

友站的简介.

一个 friend 示例:

1
2
3


{{< friend "wiz" "https://github.com/willrealize/" "https://pic.imgdb.cn/item/629a49520947543129545413.png" "This is wiz~💤" >}}
或者
{{< friend name="wiz" url="https://github.com/willrealize/" avatar="https://pic.imgdb.cn/item/629a49520947543129545413.png" bio="This is wiz~💤" >}}

呈现的输出效果如下:

showcase

showcase 用于在页面上插入一个个人项目的展示柜.

showcase shortcode 有以下命名参数:

title [required] (第一个位置参数)

项目名称.
summary [required] (第二个位置参数)

项目简介.
image [required] (第三个位置参数)

预览图的链接.
link [required] (第四个位置参数)

项目主页的链接.
column [optional] (fifth positional parameter)

这个参数定义一行显示几个 showcase. 默认的值是 2, 默认一行显示两个 showcase. 你可以将它改为 1, 2 或 3. 需要注意的是, 当用户使用小屏幕访问网站时, 每行显示的 showcase 数量将会被自动调整以保证最好的体验.

一个 showcase 示例:

1
2
3


{{< showcase title="Theme Documentation - Basics" summary="Discover what the Hugo - DoIt theme is all about and the core-concepts behind it." image="/theme-documentation-basics/featured-image.webp" link="/theme-documentation-basics" >}}
Or
{{< showcase "Theme Documentation - Basics" "Discover what the Hugo - DoIt theme is all about and the core-concepts behind it." "/theme-documentation-basics/featured-image.webp" "/theme-documentation-basics" >}}

呈现的输出效果如下:

https://pic.imgdb.cn/item/629a49d0094754312954f801.png

Hugo搭建个人博客网站

探索 Hugo - DoIt 主题的全部内容和背后的核心概念.

点击查看

math

math 用于插入数学公式. 它可以阻止 Goldmark 将数学表达式中的特殊字符解析为 HTML 从而避免很多问题. 在 math 中, 你不再需要转义特殊字符.

一个 math 示例:

1
2
3
4
5


{{< math >}}$\|\boldsymbol{x}\|_{0}=\sqrt[0]{\sum_{i} x_{i}^{0}}${{< /math >}}
Or
{{< math >}}
$$\|\boldsymbol{x}\|_{0}=\sqrt[0]{\sum_{i} x_{i}^{0}}$$
{{< /math >}}

呈现的输出效果如下:

$\|\boldsymbol{x}\|_{0}=\sqrt[0]{\sum_{i} x_{i}^{0}}$

或:

$$\|\boldsymbol{x}\|_{0}=\sqrt[0]{\sum_{i} x_{i}^{0}}$$

目录

Hugo文档 - 5. Shortcodes

内置shortcodes

figure

Hugo

highlight

扩展shortcodes

link

image

admonition

music

自定义音乐 URL

音乐平台 URL 的自动识别

自定义音乐平台, 类型和 ID

其它参数

bilibili

typeit

简单内容

代码内容

分组内容

friend

showcase

Hugo搭建个人博客网站

math