扩展 Shortcodes 夏洛魂的个人博客

夏洛魂收录于 Markdown

2022-06-06 约 3500 字预计阅读 7 分钟

/posts/markdown/%E6%89%A9%E5%B1%95-shortcodes/images/featured-image.jpg

LoveIt 主题在 Hugo 内置的 shortcode 的基础上提供多个扩展的 Shortcode.

style

注意

Hugo extended 版本对于 style shortcode 是必需的.

style shortcode 用来在你的文章中插入自定义样式.

style shortcode 有两个位置参数.

第一个参数是自定义样式的内容. 它支持 SASS 中的嵌套语法, 并且 & 指代这个父元素.

第二个参数是包裹你要更改样式的内容的 HTML 标签, 默认值是 div.

一个 style 示例:

1
2
3


{{< style "text-align:right; strong{color:#00b1ff;}" >}}
This is a **right-aligned** paragraph.
{{< /style >}}

呈现的输出效果如下:

This is a right-aligned paragraph.

link

link shortcode 有以下命名参数:

href [必需]（第一个位置参数）

链接的目标。
content [可选]（第二个位置参数）

链接的内容，默认值是 href 参数的值。

支持 Markdown 或者 HTML 格式。
title [可选]（第三个位置参数）

HTML a 标签的 title 属性，当悬停在链接上会显示的提示。
card [可选]（第四个位置参数

是否显示为卡片式链接，默认值 false。
card-icon [可选] (第五个位置参数)

卡片式链接的图标，支持图片链接和 Font Awesome 图标。设置为 true，自动从链接获取缩略图。
download [可选]

HTML a 标签的 download 属性。
class [可选]

HTML a 标签的 class 属性。
rel [可选]

HTML a 标签的 rel 补充属性。
external-icon [可选]

是否自动显示外链图标。
noreferrer [可选]

rel 属性是否添加 noreferrer, 默认：true。

一个 link 示例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{{< link "https://xialuohun.top" >}}
或者
{{< link href="https://xialuohun.top >}}

{{< link "https://xialuohun.top" >}}
或者
{{< link href="https://xialuohun.top" >}}

{{< link "https://xialuohun.top" xialuohun >}}
或者
{{< link href="https://xialuohun.top" content=xialuohun >}}

呈现的输出效果如下:

一个带有标题的 link 示例:

1
2
3


{{< link "https://xialuohun.top" "" "XiaLuoHun" >}}
或者
{{< link href="https://xialuohun.top" content="" title="XiaLuoHun" >}}

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

https://xialuohun.top

一个卡片式 link 示例：

1

{{< link "https://xialuohun.top" "XiaLuoHun" "" true "/images/Luo.png" >}}

呈现的输出效果如下：

XiaLuoHun https://xialuohun.top

admonition

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

支持 Markdown 或者 HTML 格式.

注意

一个注意横幅

摘要

一个摘要横幅

信息

一个信息横幅

技巧

一个技巧横幅

成功

一个成功横幅

问题

一个问题横幅

警告

一个警告横幅

失败

一个失败横幅

危险

一个危险横幅

Bug

一个 Bug 横幅

示例

一个示例横幅

引用

一个引用横幅

admonition shortcode 有以下命名参数:

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

admonition 横幅的类型, 默认值是 note.

1
2


//参数如下
note abstract info tip success question warning failure danger bug example quote 

title [可选] (第二个位置参数)

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

横幅内容是否默认展开, 默认值是 true.

一个 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

一个技巧横幅

mermaid

一个 流程图 mermaid 示例:

1
2
3
4
5
6
7


{{< mermaid >}}
graph LR;
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
{{< /mermaid >}}

呈现的输出效果如下:

graph LR;
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]

时序图

一个 时序图 mermaid 示例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


{{< mermaid >}}
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail...
    John-->Alice: Great!
    John->Bob: How about you?
    Bob-->John: Jolly good!
{{< /mermaid >}}

呈现的输出效果如下:

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->John: Fight against hypochondria
    end
    Note right of John: Rational thoughts 
prevail...
    John-->Alice: Great!
    John->Bob: How about you?
    Bob-->John: Jolly good!

甘特图

一个 甘特图 mermaid 示例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


{{< mermaid >}}
gantt
    dateFormat  YYYY-MM-DD
    title Adding GANTT diagram functionality to mermaid
    section A section
    Completed task            :done,    des1, 2014-01-06,2014-01-08
    Active task               :active,  des2, 2014-01-09, 3d
    Future task               :         des3, after des2, 5d
    Future task2               :         des4, after des3, 5d
    section Critical tasks
    Completed task in the critical line :crit, done, 2014-01-06,24h
    Implement parser and jison          :crit, done, after des1, 2d
    Create tests for parser             :crit, active, 3d
    Future task in critical line        :crit, 5d
    Create tests for renderer           :2d
    Add to mermaid                      :1d
{{< /mermaid >}}

呈现的输出效果如下:

gantt
    dateFormat  YYYY-MM-DD
    title Adding GANTT diagram functionality to mermaid
    section A section
    Completed task            :done,    des1, 2014-01-06,2014-01-08
    Active task               :active,  des2, 2014-01-09, 3d
    Future task               :         des3, after des2, 5d
    Future task2               :         des4, after des3, 5d
    section Critical tasks
    Completed task in the critical line :crit, done, 2014-01-06,24h
    Implement parser and jison          :crit, done, after des1, 2d
    Create tests for parser             :crit, active, 3d
    Future task in critical line        :crit, 5d
    Create tests for renderer           :2d
    Add to mermaid                      :1d

类图

一个类图 mermaid 示例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{{< mermaid >}}
classDiagram
    Class01 <|-- AveryLongClass : Cool
    Class03 *-- Class04
    Class05 o-- Class06
    Class07 .. Class08
    Class09 --> C2 : Where am i?
    Class09 --* C3
    Class09 --|> Class07
    Class07 : equals()
    Class07 : Object[] elementData
    Class01 : size()
    Class01 : int chimp
    Class01 : int gorilla
    Class08 <--> C2: Cool label
{{< /mermaid >}}

呈现的输出效果如下:

classDiagram
    Class01 <|-- AveryLongClass : Cool
    Class03 *-- Class04
    Class05 o-- Class06
    Class07 .. Class08
    Class09 --> C2 : Where am i?
    Class09 --* C3
    Class09 --|> Class07
    Class07 : equals()
    Class07 : Object[] elementData
    Class01 : size()
    Class01 : int chimp
    Class01 : int gorilla
    Class08 <--> C2: Cool label

状态图

一个 状态图 mermaid 示例:

1
2
3
4
5
6
7
8
9


{{< mermaid >}}
stateDiagram
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
{{< /mermaid >}}

呈现的输出效果如下:

stateDiagram
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

Git 图

一个 Git 图 mermaid 示例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


{{< mermaid >}}
gitGraph:
options
{
    "nodeSpacing": 100,
    "nodeRadius": 10
}
end
    commit
    branch newbranch
    checkout newbranch
    commit
    commit
    checkout master
    commit
    commit
    merge newbranch
{{< /mermaid >}}

呈现的输出效果如下:

gitGraph:
options
{
    "nodeSpacing": 100,
    "nodeRadius": 10
}
end
    commit
    branch newbranch
    checkout newbranch
    commit
    commit
    checkout master
    commit
    commit
    merge newbranch

饼图

一个饼图 mermaid 示例:

1
2
3
4
5
6


{{< mermaid >}}
pie
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15
{{< /mermaid >}}

呈现的输出效果如下:

pie
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15

typeit

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

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

简单内容

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

一个 typeit 示例:

1
2
3


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

呈现的输出效果如下:

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

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

1
2
3


{{< 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 >}}

呈现的输出效果如下:

script

script shortcode 用来在你的文章中插入 Javascript 脚本.

注意

脚本内容可以保证在所有的第三方库加载之后按顺序执行. 所以你可以自由地使用第三方库.

一个 script 示例:

1
2
3


{{< script >}}
console.log('Hello XiaLuoHun!');
{{< /script >}}

你可以在开发者工具的控制台中看到输出.

自定义属性

前提是你设置了 goldmark.parser.attribute.block 为 true。

Hugo 支持向 Markdown 块添加属性（例如 CSS 类），例如表格、列表、段落等。

语法:

1
2


some Markdown content
{#id .class1 .class2 key1="value1" key2="value2"}

在大多数情况下，将属性列表放置在标记元素下方。对于标题和围栏代码块，将属性列表放在右侧。

标记元素	属性放置的位置
blockquote	底部
fenced code block	右侧
heading	右侧
horizontal rule	底部
image	底部
list	底部
paragraph	底部
table	底部

例子:

带有 CSS 类的分割线：

1
2


---
{.awesome-hr}

呈现的输出如下所示:

带有 CSS 类的块引用：

1
2
3


> foo\
> bar
{#test-id .text-danger}

呈现的输出如下所示：

foo
bar

目前有一些限制：对于表格，你目前只能将其应用于完整表格，而对于列表，仅适用于 ul/ol 节点，例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


* 水果
  * 苹果
  * 橙子
  * 香蕉
  {.text-success}
* 乳制品
  * 牛奶
  * 奶酪
  {.text-warning}
{.text-primary}

呈现的输出如下所示：

水果
- 苹果
- 橙子
- 香蕉
乳制品
- 牛奶
- 奶酪

给代码块添加 title 属性，例如：

1
2
3


```js {title="Luo.js"}
console.log('hello XiaLuoHun!');
```

呈现的输出效果如下：

1

console.log('hello XiaLuoHun!');

警示

警示也被称为callouts或admonitions,是用于强调关键信息的引用块。以下是所有五种类型的示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


> [!NOTE]
> 突出显示用户应考虑的信息，即使只是浏览也应考虑。

> [!TIP]
> 可选信息，可帮助用户取得更大的成功。

> [!IMPORTANT]
> 用户成功所需的关键信息。

> [!WARNING]
> 由于存在潜在风险，需要用户立即关注的关键内容。

> [!CAUTION]
> 操作的潜在负面后果。

它们的显示方式如下：

注意

突出显示用户应考虑的信息，即使只是浏览也应考虑。

提示

可选信息，可帮助用户取得更大的成功。

重要

用户成功所需的关键信息。

警告

由于存在潜在风险，需要用户立即关注的关键内容。

小心

操作的潜在负面后果。

标记文本

Hugo支持一种标记文本 Markdown扩展语法：

1

==个人博客== https://xialuohun.top/

呈现的输出效果如下：

个人博客 https://xialuohun.top/

扩展的标记文本语法支持6种类型的标记文本。

1
2
3
4
5
6


==Primary==[primary]
==Secondary==[secondary]
==Success==[success]
==Info==[info]
==Warning==[warning]
==Danger==[danger]

呈现的输出效果如下：

Primary Secondary Success Info Warning Danger

除非你自定义标记文本，否则任何不支持的类型都会默认为default类型。

1

==这是一个带有粉色的自定义类型。==[pink]

在你的项目目录assets/css/_custom.scss中添加以下 CSS 来自定义标记文本：

1
2
3


.mark-pink {
  --fi-mark-background-color: pink;
}

呈现的输出效果如下：

这是一个带有粉色的自定义类型。

输出的 HTML 看起来像这样：

1

<mark class="mark-pink">这是一个带有粉色的自定义类型。</mark>

扩展 Shortcodes

style

link

admonition

mermaid

时序图

甘特图

类图

状态图

Git 图

饼图

typeit

简单内容

代码内容

分组内容

script

自定义属性

警示

标记文本

相关内容