29 KiB
| title | date | draft | description | slug | tags | series | series_order | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 简码 | 2020-08-11 | false | 所有 Blowfish 中可用的简码 | shortcodes |
|
|
8 |
除了所有默认 Hugo 简码 之外，Blowfish 还添加了一些额外的功能。
Alert
alert 可以将其中内容输出为文章中的风格化消息框。它对于吸引读者注意您不想让读者错过的重要信息很有用。
| 参数 | 功能 |
|---|---|
icon |
可选 显示在左侧的图标。 默认： exclaimation triangle icon (查看图标简码，了解有关使用图标的更多详细信息。) |
iconColor |
可选 基本 CSS 样式中图标的颜色。 可以是十六进制值 ( #FFFFFF) 或颜色名称 (white)默认情况下由当前配色方案决定。 |
cardColor |
可选 基本 CSS 样式中卡片背景的颜色。 可以是十六进制值 ( #FFFFFF) 或颜色名称 (white)默认情况下由当前配色方案决定。 |
textColor |
可选 基本 CSS 样式中文本的颜色。 可以是十六进制值 ( #FFFFFF) 或颜色名称 (white)默认情况下由当前配色方案决定。 |
输入内容是用 Markdown 语言编写的，因此您可以根据需要设置其格式。
例1: 无参数
{{</* alert */>}}
**警告！**此操作具有破坏性！
{{</* /alert */>}}
{{< alert >}} **警告！**此操作具有破坏性！ {{< /alert >}}
例2: 未命名参数
{{</* alert "twitter" */>}}
Don't forget to [follow me](https://twitter.com/nunocoracao) on Twitter.
{{</* /alert */>}}
{{< alert "twitter" >}} Don't forget to follow me on Twitter. {{< /alert >}}
例3: 命名参数
{{</* alert icon="fire" cardColor="#e63946" iconColor="#1d3557" textColor="#f1faee" */>}}
This is an error!
{{</* /alert */>}}
{{< alert icon="fire" cardColor="#e63946" iconColor="#1d3557" textColor="#f1faee" >}} This is an error! {{< /alert >}}
Article
Article 将把一篇文章嵌入到一个 markdown 文件中。 参数中的 link应该是要嵌入的文件的 .RelPermalink。请注意，如果简码引用其父级文件，则它不会显示任何内容。 注意：如果您在 Blowfish（即 /blowfish/）等子文件夹中运行网站，请在链接中包含该路径。
| 参数 | 功能 |
|---|---|
link |
必填 要嵌入文章的 .RelPermalink |
例如：
{{</* article link="/zh-cn/docs/welcome/" */>}}
{{< article link="/zh-cn/docs/welcome/" >}}
Badge
badge 输出一个美观的徽章组件，该组件对于显示元数据很有用。
例如：
{{</* badge */>}}
New article!
{{</* /badge */>}}
{{< badge >}} New article! {{< /badge >}}
Button
button 输出一个样式化的按钮组件，可用于突出显示主要操作。它有两个可选参数 href 和 target ，可用于指定链接的 URL 或目标文档。
例如：
{{</* button href="#button" target="_self" */>}}
Call to action
{{</* /button */>}}
{{< button href="#button" target="_self" >}} Call to action {{< /button >}}
Carousel
carousel 用于生成可交互且具有视觉吸引力的方式展示多个图像的画廊。这允许用户滑动浏览多个图像，同时仅占用单个图像的垂直空间。 所有图像均使用父组件的完整宽度并使用预定义的宽高比 16:9 、 21:9 或 32:9 之一显示。
| 参数 | 功能 |
|---|---|
images |
必填 用于匹配图像名称的正则表达式或 URL。 |
aspectRatio |
可选 画廊的纵横比。16-9 、21-9 或32-9 。默认设置为16-9 。 |
interval |
可选 自动滚动的时间间隔，以毫秒为单位指定。默认为2000（2 秒）。 |
例1: 16:9 宽高比和 URL 图像列表
{{</* carousel images="{https://cdn.pixabay.com/photo/2016/12/11/12/02/mountains-1899264_960_720.jpg, gallery/03.jpg, gallery/01.jpg, gallery/02.jpg, gallery/04.jpg}" */>}}
{{< carousel images="{https://cdn.pixabay.com/photo/2016/12/11/12/02/mountains-1899264_960_720.jpg,gallery/03.jpg,gallery/01.jpg,gallery/02.jpg,gallery/04.jpg}" >}}
例2: 21:9 宽高比和正则表达式图像列表
{{</* carousel images="gallery/*" aspectRatio="21-9" interval="2500" */>}}
{{< carousel images="gallery/*" aspectRatio="21-9" interval="2500" >}}
Chart
chart 使用 Chart.js 库将图表嵌入到使用简单结构化数据的文章中。它支持多种不同的图表样式，并且所有内容都可以在简码中进行配置。只需在简码中提供图表参数，Chart.js 将完成剩下的工作。
有关语法和支持的图表类型的详细信息，请参阅 Chart.js 官方文档。
例如：
{{</* chart */>}}
type: 'bar',
data: {
labels: ['Tomato', 'Blueberry', 'Banana', 'Lime', 'Orange'],
datasets: [{
label: '# of votes',
data: [12, 19, 3, 5, 3],
}]
}
{{</* /chart */>}}
{{< chart >}} type: 'bar', data: { labels: ['Tomato', 'Blueberry', 'Banana', 'Lime', 'Orange'], datasets: [{ label: '# of votes', data: [12, 19, 3, 5, 3], }] } {{< /chart >}}
您可以在 [图表示例]({{< ref "charts" >}}) 页面上查看一些更多 Chart.js 示例。
Figure
Blowfish 包含一个 figure 简码，用于将图像添加到内容中。该简码取代了基本的 Hugo 功能，且性能更好。
当提供的图像是页面资源时，将使用 Hugo Pipes 对其进行优化并缩放，以提供适合不同设备分辨率的图像。如果提供了静态资产或外部图像的 URL，它将按原样包含在内，而无需 Hugo 进行任何图像处理。
figure 简码接受六个参数：
| 参数 | 功能 |
|---|---|
src |
必填 图像的本地路径/文件名或 URL。当提供路径和文件名时，主题将尝试使用以下查找顺序来查找图像：首先，作为与页面绑定的页面资源；然后是 assets/ 目录中的文件；最后是，static/目录中的文件。 |
alt |
图像的替代文本描述。 |
caption |
Markdown 格式的图像标题，将显示在图像下方。 |
class |
应用于图像的其他 CSS 类。 |
href |
图像应链接到的 URL。 |
target |
href URL 的目标属性。 |
nozoom |
nozoom=true 会禁用图像缩放功能。与 href 结合使用十分有用。 |
default |
用于恢复默认 Hugo figure 行为的特殊参数。只需提供default=true，然后使用正常的 Hugo 简码语法。 |
Blowfish 还支持使用标准 Markdown 语法自动转换图像。只需使用以下格式，主题将自动处理：
例如：
{{</* figure
src="abstract.jpg"
alt="Abstract purple artwork"
caption="Photo by [Jr Korpa](https://unsplash.com/@jrkorpa) on [Unsplash](https://unsplash.com/)"
*/>}}
<!-- OR -->
{{< figure src="abstract.jpg" alt="Abstract purple artwork" caption="Photo by Jr Korpa on Unsplash" >}}
Gallery
gallery 允许您以响应式一次展示多个图像，并具有更加多样化和有趣的布局的图库。
为了将图像添加到图库中，请为每个图像使用img标签并添加class ="grid-wXX"，以便图库能够识别每个图像的列宽。默认情况下可用的宽度从 10% 开始，以 5% 的增量一直达到 100%。例如，要将宽度设置为 65%，请将类设置为grid-w65。此外，还可以使用 33% 和 66% 的宽度来构建 3 列的画廊。您还可以利用 Tailwind 的响应指示器来构建响应网格。
例1: 普通图库
{{</* gallery */>}}
<img src="gallery/01.jpg" class="grid-w33" />
<img src="gallery/02.jpg" class="grid-w33" />
<img src="gallery/03.jpg" class="grid-w33" />
<img src="gallery/04.jpg" class="grid-w33" />
<img src="gallery/05.jpg" class="grid-w33" />
<img src="gallery/06.jpg" class="grid-w33" />
<img src="gallery/07.jpg" class="grid-w33" />
{{</* /gallery */>}}
{{< gallery >}}
{{< /gallery >}}
例2: 响应式图库
{{</* gallery */>}}
<img src="gallery/01.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
<img src="gallery/02.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
<img src="gallery/03.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
<img src="gallery/04.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
<img src="gallery/05.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
<img src="gallery/06.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
<img src="gallery/07.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
{{</* /gallery */>}}
{{< gallery >}}
{{< /gallery >}}
GitHub 卡片
github 允许您快速链接到 github Repo，同时显示和更新有关它的实时统计信息，例如它的 star 和 fork 数。
| 参数 | 功能 |
|---|---|
repo |
[String] 格式为 username/repo 的 github repo |
例1:
{{</* github repo="nunocoracao/blowfish" */>}}
{{< github repo="nunocoracao/blowfish" >}}
GitLab 卡片
gitlab 允许您快速链接 GitLab 项目（GitLab 的 Repo）。
显示有关的实时统计数据，例如它拥有的 star 和 fork 的数量。
与 github 不同，它无法显示项目的主要编程语言。
最后，只要 api/v4/projects/ 可用，就可以提供自定义 GitLab 实例 URL，从而使此简码能够显示大多数自托管/企业组织。
| 参数 | 功能 |
|---|---|
projectID |
[String] gitlab 数字项目ID |
baseURL |
[String] 可选 gitlab 实例 URL，默认为 https://gitlab.com/ |
例1:
{{</* gitlab projectID="278964" */>}}
{{< gitlab projectID="278964" >}}
图标
icon 输出一个 SVG 图标并以图标名称作为其唯一参数。图标会自动缩放以匹配当前文本大小。
例如：
{{</* icon "github" */>}}
Output: {{< icon "github" >}}
图标使用 Hugo Pipeline 填充，这使得它们非常灵活。 Blowfish 包含许多用于社交、链接和其他内置图标。参考 [图标示例]({{< ref "samples/icons" >}}) 页面以获取支持的图标的完整列表。
可以通过在项目的 assets/icons/ 目录中提供您自己的图标来添加自定义图标。然后可以使用不带 .svg 扩展名的 SVG 文件名在简码中引用该图标。
还可以通过调用 [iconpartial]({{< ref "partials#icon" >}}) 在 partials 中使用图标。
KaTeX
katex 简码可用于使用 KaTeX 包向文章内容添加数学表达式。有关可用语法，请参阅支持的 TeX 函数 的在线参考。
要在文章中加入数学表达式，只需将简码放在任意位置即可。每篇文章只需加入一次，KaTeX 将自动呈现该页面上的任何标记。支持内联和块表示法。
可以通过将表达式包装在 \\( 和 \\) 分隔符中来生成内联表示法。或者，可以使用 $$ 分隔符生成块符号。
例如：
{{</* katex */>}}
\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
{{< katex >}} \(f(a,b,c) = (a^2+b^2+c^2)^3\)
查看 [数学符号示例]({{< ref "mathematical-notation" >}}) 页面以获取更多示例。
重点突出
keyword 组件可用于在视觉上突出显示某些重要的单词或短语，例如专业技能等。 keywordList 简码可用于将多个 keyword 组合在一起。每个组件可以具有以下参数。
| 参数 | 功能 |
|---|---|
icon |
可选 关键字中使用的图标 |
输入内容是用 Markdown 编写的，因此您可以根据需要设置其格式。
例1 :
{{</* keyword */>}} Super skill {{</* /keyword */>}}
{{< keyword >}} Standalone skill {{< /keyword >}}
例2 :
{{</* keywordList */>}}
{{</* keyword icon="github" */>}} Lorem ipsum dolor. {{</* /keyword */>}}
{{</* keyword icon="code" */>}} **Important** skill {{</* /keyword */>}}
{{</* /keywordList */>}}
{{</* keyword */>}} *Standalone* skill {{</* /keyword */>}}
{{< keywordList >}} {{< keyword icon="github" >}} Lorem ipsum dolor {{< /keyword >}} {{< keyword icon="code" >}} Important skill {{< /keyword >}} {{< /keywordList >}} {{< keyword >}} Standalone skill {{< /keyword >}}
Lead
lead 用于强调文章的开头。它可以用来设计介绍的样式，或者指出一条重要的信息。只需将任何 Markdown 内容包装在 lead 简码中即可。
例如：
{{</* lead */>}}
When life gives you lemons, make lemonade.
{{</* /lead */>}}
{{< lead >}} When life gives you lemons, make lemonade. {{< /lead >}}
列表
List 将显示最近文章的列表。此简码需要一个限制值来约束列表。此外，它还支持输入 where 和 value ，以便按参数过滤文章。请注意，此简码不会显示其父页面，但会计入限制值。
| 参数 | 功能 |
|---|---|
limit |
必填 要显示的最近文章数量。 |
title |
可选 列表标题，默认为 Recent |
cardView |
可选 列表启用卡片视图，默认为 false |
where |
用于筛选文章的变量，例如 Type |
value |
需要与 where 中定义的参数匹配的值，以进行文章查询，例如对于 where == Type，可以找到文章 sample |
{{< alert >}}
where 和 value 值用于简码中进行以下格式的查询 where .Site.RegularPages $where $value 。检查 Hugo 文档 以了解有关可用参数的更多信息。
{{</ alert >}}
例 1:
{{</* list limit=2 */>}}
{{< list limit=2 >}}
例 2:
{{</* list title="Samples" cardView=true limit=5 where="Type" value="sample" */>}}
{{< list title="Samples" cardView=true limit=6 where="Type" value="sample">}}
文字书写方向
ltr 和 rtl 允许您混排内容。许多从左往右书写语言的用户希望在文章中包含部分从右往左的书写内容。使用此简码可以让您做到这一点，并利用 % 作为简码中最外层的标识符 Hugo Shortcodes，其中任何 markdown 内容都会正常渲染。
例如：
- This is an markdown list.
- Its per default a LTR direction
{{%/* rtl */%}}
- هذه القائمة باللغة العربية
- من اليمين الى اليسار
{{%/* /rtl */%}}
- This is an markdown list.
- Its per default a LTR direction {{% rtl %}}
- هذه القائمة باللغة العربية
- من اليمين الى اليسار {{% /rtl %}}
Markdown 导入
此简码允许您从外部源导入 Markdown 文件。这对于包含来自其他仓库或网站的内容非常有用，而无需复制和粘贴内容。
| 参数 | 功能 |
|---|---|
url |
必填 外部托管 Markdown 文件的 URL。 |
例如：
{{</* mdimporter url="https://raw.githubusercontent.com/nunocoracao/nunocoracao/master/README.md" */>}}
{{< mdimporter url="https://raw.githubusercontent.com/nunocoracao/nunocoracao/master/README.md" >}}
Mermaid
mermaid 允许您使用文本绘制可视化的图表。底层使用 Mermaid，并支持各种图表、图表和其他输出格式。
只需在 mermaid 简码中编写您的 Mermaid 语法，然后让插件完成其余的工作。
有关语法和支持的图表类型的详细信息，请参阅官方 Mermaid 文档。
例如：
{{</* mermaid */>}}
graph LR;
A[Lemons]-->B[Lemonade];
B-->C[Profit]
{{</* /mermaid */>}}
{{< mermaid >}} graph LR; A[Lemons]-->B[Lemonade]; B-->C[Profit] {{< /mermaid >}}
您可以在[图表和流程图示例]({{< ref "diagrams-flowcharts" >}}) 页面上看到一些其他 Mermaid 示例。
色板
swatches 输出一组最多三种不同的颜色来展示颜色元素的调色板。该简码采用每种颜色的 HEX 码并为每种颜色创建预览。
例
{{</* swatches "#64748b" "#3b82f6" "#06b6d4" */>}}
输出 {{< swatches "#64748b" "#3b82f6" "#06b6d4" >}}
时间线
timeline 创建了一个可视化时间线，用于展示专业经验、项目成就等。 timeline 简码依赖于 timelineItem 子简码来定义主时间线中的每个项目。每个项目可以具有以下属性。
| 参数 | 功能 |
|---|---|
icon |
要在时间线中使用的图标。 |
header |
每个条目的标题 |
badge |
放置在右上角徽章内的文本 |
subheader |
每个条目的副标题 |
例如：
{{</* timeline */>}}
{{</* timelineItem icon="github" header="header" badge="badge test" subheader="subheader" */>}}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus non magna ex. Donec sollicitudin ut lorem quis lobortis. Nam ac ipsum libero. Sed a ex eget ipsum tincidunt venenatis quis sed nisl. Pellentesque sed urna vel odio consequat tincidunt id ut purus. Nam sollicitudin est sed dui interdum rhoncus.
{{</* /timelineItem */>}}
{{</* timelineItem icon="code" header="Another Awesome Header" badge="date - present" subheader="Awesome Subheader" */>}}
With html code
<ul>
<li>Coffee</li>
<li>Tea</li>
<li>Milk</li>
</ul>
{{</* /timelineItem */>}}
{{</* timelineItem icon="star" header="Shortcodes" badge="AWESOME" */>}}
With other shortcodes
{{</* gallery */>}}
<img src="gallery/01.jpg" class="grid-w33" />
<img src="gallery/02.jpg" class="grid-w33" />
<img src="gallery/03.jpg" class="grid-w33" />
<img src="gallery/04.jpg" class="grid-w33" />
<img src="gallery/05.jpg" class="grid-w33" />
<img src="gallery/06.jpg" class="grid-w33" />
<img src="gallery/07.jpg" class="grid-w33" />
{{</* /gallery */>}}
{{</* /timelineItem */>}}
{{</* /timeline */>}}
{{< timeline >}}
{{< timelineItem icon="github" header="header" badge="badge test" subheader="subheader" >}} Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus non magna ex. Donec sollicitudin ut lorem quis lobortis. Nam ac ipsum libero. Sed a ex eget ipsum tincidunt venenatis quis sed nisl. Pellentesque sed urna vel odio consequat tincidunt id ut purus. Nam sollicitudin est sed dui interdum rhoncus. {{</ timelineItem >}}
{{< timelineItem icon="code" header="Another Awesome Header" badge="date - present" subheader="Awesome Subheader">}} With html code
- Coffee
- Tea
- Milk
{{< timelineItem icon="star" header="Shortcodes" badge="AWESOME" >}}
With other shortcodes
{{< gallery >}}
{{< /gallery >}}
{{</ timelineItem >}}
{{</ timeline >}}
TypeIt
TypeIt 是用于创建打字机效果的最通用的 JavaScript 工具。通过简单的配置，它允许您键入单个或多个断行、删除和相互替换的字符串，甚至可以处理包含复杂 HTML 的字符串。
Blowfish 使用简码实现 TypeIt 功能的子集。在 typeit 简码中编写文本，并使用以下参数来配置您想要的行为。
| 参数 | 功能 |
|---|---|
tag |
[String] 将用于呈现字符串的 html 标签。 |
classList |
[String] 应用于 html 元素的 css 类列表。 |
initialString |
[String] 将显示为先写入并将被替换的初始字符串。 |
speed |
[number] 每步之间的打字速度，以毫秒为单位。 |
lifeLike |
[boolean] 使打字速度不规律，就像真人在打字一样。 |
startDelay |
[number] 插件在初始化后到开始输入的延迟时间。 |
breakLines |
[boolean] 将多个字符串换行输出 (true)，或者将它们删除并替换 (false)。 |
waitUntilVisible |
[boolean] 决定脚本在网站加载时启动还是在目标元素可见时启动。默认为 true |
loop |
[boolean] 字符串动画是否会循环 |
例1:
{{</* typeit */>}}
Lorem ipsum dolor sit amet
{{</* /typeit */>}}
{{< typeit >}} Lorem ipsum dolor sit amet {{< /typeit >}}
例2:
{{</* typeit
tag=h1
lifeLike=true
*/>}}
Lorem ipsum dolor sit amet,
consectetur adipiscing elit.
{{</* /typeit */>}}
{{< typeit tag=h1 lifeLike=true
}} Lorem ipsum dolor sit amet, consectetur adipiscing elit. {{< /typeit >}}
例3:
{{</* typeit
tag=h3
speed=50
breakLines=false
loop=true
*/>}}
Lorem ipsum dolor sit amet,
consectetur adipiscing elit.
{{</* /typeit */>}}
{{< typeit tag=h3 speed=50 breakLines=false loop=true
}} "Frankly, my dear, I don't give a damn." Gone with the Wind (1939) "I'm gonna make him an offer he can't refuse." The Godfather (1972) "Toto, I've a feeling we're not in Kansas anymore." The Wizard of Oz (1939) {{< /typeit >}}
Youtube 嵌入播放器
使用 lite-youtube-embed 库嵌入 YouTube 视频的简码。该库是 YouTube 嵌入播放器的轻量级替代品，其设计速度更快、更高效。
| 参数 | 功能 |
|---|---|
id |
[String] 要嵌入的 YouTube 视频 ID。 |
label |
[String] 视频的标签 |
例1:
{{</* youtubeLite id="SgXhGb-7QbU" label="Blowfish-tools demo" */>}}
{{< youtubeLite id="SgXhGb-7QbU" label="Blowfish-tools demo" >}}