description: "Learn how to group articles under a series."
description: "了解如何将文章分组到系列中。"
slug: "series"
tags: ["series", "docs"]
series: ["Documentation"]
tags: ["系列", "文档"]
series: ["部署教程"]
series_order: 11
seriesOpened: true
---
Blowfish provides a feature to group a set of articles together under a "series". Placing an article under a series will display the rest of the series articles in each single page and provide a quick way to navigate amongst them. You can see an example of this above.
The first step to enable series is to create the `series` taxonomy. For doing this just add the `series` taxonomy to your taxonomy list in the `config.toml`.
@ -23,14 +23,15 @@ The first step to enable series is to create the `series` taxonomy. For doing th
series = "series"
```
## Mark Articles
## 标记文章
Then you just need to mark each article using the `series` parameter and the `series_order`. The `series` parameter will be the id and name of the series you are placing the article into (even though the variable is an array we recommend keeping each article to a single series.). And the `series_order` defines the order of that article within the series. In the example below the article is number `11` in the `Documentation` series.
Marking an article as part of a series will automatically display the series module as you see in this page for example. You can choose whether that module starts opened or not using the `article.seriesOpened` global variable in `params.toml` or the front-matter parameter `seriesOpened` to specify an override at the article level.
In addition to all the [default Hugo shortcodes](https://gohugo.io/content-management/shortcodes/), Blowfish adds a few extras for additional functionality.
除了所有[默认 Hugo 简码](https://gohugo.io/content-management/shortcodes/) 之外，Blowfish 还添加了一些额外的功能。
## Alert
`alert`outputs its contents as a stylised message box within your article. It's useful for drawing attention to important information that you don't want the reader to miss.
| `icon` | **Optional.** the icon to display on the left side.<br>**Default:** `exclaimation triangle icon` (Check out the [icon shortcode](#icon) for more details on using icons.) |
| `iconColor` | **Optional.** the color for the icon in basic CSS style.<br>Can be either hex values (`#FFFFFF`) or color names (`white`)<br>By default chosen based on the current color theme . |
| `cardColor` | **Optional.** the color for the card background in basic CSS style.<br>Can be either hex values (`#FFFFFF`) or color names (`white`)<br>By default chosen based on the current color theme . |
| `textColor` | **Optional.** the color for the text in basic CSS style.<br>Can be either hex values (`#FFFFFF`) or color names (`white`)<br>By default chosen based on the current color theme . |
`Article`will embed a single article into a markdown file. The `link` to the file should be the `.RelPermalink` of the file to be embedded. Note that the shortcode will not display anything if it's referencing it's parent. *Note: if you are running your website in a subfolder like Blowfish (i.e. /blowfish/) please include that path in the link.*
| `link` | **Required.** the `.RelPermalink` to the target article. |
| `link` | **必填** 要嵌入文章的 `.RelPermalink` |
<!-- prettier-ignore-end -->
**Example:**
**例如：**
```md
{{</* article link="/docs/welcome/" */>}}
@ -86,9 +86,9 @@ This is an error!
## Badge
`badge`outputs a styled badge component which is useful for displaying metadata.
`badge`输出一个美观的徽章组件，该组件对于显示元数据很有用。
**Example:**
**例如：**
```md
{{</* badge */>}}
@ -104,9 +104,9 @@ New article!
## Button
`button`outputs a styled button component which can be used to highlight a primary action. It has two optional variables `href` and `target` which can be used to specify the URL and target of the link.
`carousel`is used to showcase multiple images in an interactive and visually appealing way. This allows a user to slide through multiple images while only taking up the vertical space of a single one. All images are displayed using the full width of the parent component and using one of the predefined aspect ratios of `16:9`, `21:9` or `32:9`.
`chart`uses the Chart.js library to embed charts into articles using simple structured data. It supports a number of [different chart styles](https://www.chartjs.org/docs/latest/samples/) and everything can be configured from within the shortcode. Simply provide the chart parameters between the shortcode tags and Chart.js will do the rest.
Blowfish includes a `figure` shortcode for adding images to content. The shortcode replaces the base Hugo functionality in order to provide additional performance benefits.
Blowfish 包含一个 `figure` 简码，用于将图像添加到内容中。该简码取代了基本的 Hugo 功能，且性能更好。
When a provided image is a page resource, it will be optimised using Hugo Pipes and scaled in order to provide images appropriate to different device resolutions. If a static asset or URL to an external image is provided, it will be included as-is without any image processing by Hugo.
当提供的图像是页面资源时，将使用 Hugo Pipes 对其进行优化并缩放，以提供适合不同设备分辨率的图像。如果提供了静态资产或外部图像的 URL，它将按原样包含在内，而无需 Hugo 进行任何图像处理。
| `src` | **Required.** The local path/filename or URL of the image. When providing a path and filename, the theme will attempt to locate the image using the following lookup order: Firstly, as a [page resource](https://gohugo.io/content-management/page-resources/) bundled with the page; then an asset in the `assets/` directory; then finally, a static image in the `static/` directory. |
| `alt` | [Alternative text description](https://moz.com/learn/seo/alt-text) for the image. |
| `caption` | Markdown for the image caption, which will be displayed below the image. |
| `class` | Additional CSS classes to apply to the image. |
| `href` | URL that the image should be linked to. |
| `target` | The target attribute for the `href` URL. |
| `nozoom` | `nozoom=true`disables the image "zoom" functionality. This is most useful in combination with a `href` link. |
| `default` | Special parameter to revert to default Hugo `figure` behaviour. Simply provide `default=true` and then use normal [Hugo shortcode syntax](https://gohugo.io/content-management/shortcodes/#figure). |
| `default` | 用于恢复默认 Hugo `figure` 行为的特殊参数。只需提供`default=true`，然后使用正常的 [Hugo 简码语法](https://gohugo.io/content-management/shortcodes/#figure)。 |
<!-- prettier-ignore-end -->
Blowfish also supports automatic conversion of images included using standard Markdown syntax. Simply use the following format and the theme will handle the rest:
@ -235,11 +235,11 @@ Blowfish also supports automatic conversion of images included using standard Ma
## Gallery
`gallery`allows you to showcase multiple images at once, in a responsive manner with more varied and interesting layouts.
`gallery`允许您以响应式一次展示多个图像，并具有更加多样化和有趣的布局的图库。
In order to add images to the gallery, use `img` tags for each image and add `class="grid-wXX"` in order for the gallery to be able to identify the column width for each image. The widths available by default start at 10% and go all the way to 100% in 5% increments. For example, to set the width to 65%, set the class to `grid-w65`. Additionally, widths for 33% and 66% are also available in order to build galleries with 3 cols. You can also leverage tailwind's responsive indicators to have a reponsive grid.
@ -266,7 +266,7 @@ In order to add images to the gallery, use `img` tags for each image and add `cl
<br/><br/><br/>
**Example 2: responsive gallery**
**例2: 响应式图库**
```md
{{</* gallery */>}}
@ -292,17 +292,17 @@ In order to add images to the gallery, use `img` tags for each image and add `cl
<br/><br/><br/>
## GitHub Card
## GitHub 卡片
`github`allows you to quickly link a github repository, all while showing and updating in realtime stats about it, such as the number of stars and forks it has.
`github`允许您快速链接到 github Repo，同时显示和更新有关它的实时统计信息，例如它的 star 和 fork 数。
@ -312,21 +312,21 @@ In order to add images to the gallery, use `img` tags for each image and add `cl
<br/><br/><br/>
## GitLab Card
## GitLab 卡片
`gitlab`allows you to quickly link a GitLab Project (GitLab's jargon for repo).
It displays realtime stats about it, such as the number of stars and forks it has.
Unlike `github` it can't display the main programming language of a project.
Finally, custom GitLab instance URL can be provided, as long as the `api/v4/projects/` endpoint is available, making this shortcode compatible with most self-hosted / enterprise deployments.
@ -336,11 +336,11 @@ Finally, custom GitLab instance URL can be provided, as long as the `api/v4/proj
<br/><br/><br/>
## Icon
## 图标
`icon`outputs an SVG icon and takes the icon name as its only parameter. The icon is scaled to match the current text size.
`icon`输出一个 SVG 图标并以图标名称作为其唯一参数。图标会自动缩放以匹配当前文本大小。
**Example:**
**例如：**
```md
{{</* icon "github" */>}}
@ -348,23 +348,23 @@ Finally, custom GitLab instance URL can be provided, as long as the `api/v4/proj
**Output:** {{<icon"github">}}
Icons are populated using Hugo pipelines which makes them very flexible. Blowfish includes a number of built-in icons for social, links and other purposes. Check the [icon samples]({{< ref "samples/icons" >}}) page for a full list of supported icons.
Custom icons can be added by providing your own icon assets in the `assets/icons/` directory of your project. The icon can then be referenced in the shortcode by using the SVG filename without the `.svg` extension.
The `katex` shortcode can be used to add mathematical expressions to article content using the KaTeX package. Refer to the online reference of [supported TeX functions](https://katex.org/docs/supported.html) for the available syntax.
To include mathematical expressions in an article, simply place the shortcode anywhere with the content. It only needs to be included once per article and KaTeX will automatically render any markup on that page. Both inline and block notation are supported.
Inline notation can be generated by wrapping the expression in `\\(` and `\\)` delimiters. Alternatively, block notation can be generated using `$$` delimiters.
The `keyword` component can be used to visually highlight certain important words or phrases, e.g. professional skills etc. The `keywordList` shortcode can be used to group together multiple `keyword` items. Each item can have the following properties.
| `icon` | Optional icon to be used in the keyword |
| `icon` | **可选** 关键字中使用的图标 |
<!-- prettier-ignore-end -->
The input is written in Markdown so you can format it however you please.
输入内容是用 Markdown 编写的，因此您可以根据需要设置其格式。
**Example1 :**
**例1 :**
```md
{{</* keyword */>}} Super skill {{</* /keyword */>}}
@ -401,7 +401,7 @@ The input is written in Markdown so you can format it however you please.
{{<keyword>}} *Standalone* skill {{</keyword>}}
**Example2 :**
**例2 :**
```md
{{</* keywordList */>}}
@ -422,9 +422,9 @@ The input is written in Markdown so you can format it however you please.
## Lead
`lead`is used to bring emphasis to the start of an article. It can be used to style an introduction, or to call out an important piece of information. Simply wrap any Markdown content in the `lead` shortcode.
@ -438,26 +438,26 @@ When life gives you lemons, make lemonade.
<br/><br/><br/>
## List
## 列表
`List`will display a list of recent articles. This shortcode requires a limit value to constraint the list. Additionally, it supports a `where` and a `value` in order to filter articles by their parameters. Note that this shortcode will not display its parent page but it will count for the limit value.
| `limit` | **Required.** the number of recent articles to display. |
| `title` | Optional title for the list, default is`Recent` |
| `cardView` | Optional card view enabled for the list, default is`false` |
| `where` | The variable to be used for the query of articles e.g.`Type` |
| `value` | The value that will need to match the parameter defined in `where` for the query of articles e.g. for `where` == `Type` a valid value could be`sample` |
The `where` and `value` values are used in the following query `where .Site.RegularPages $where $value` in the code of the shortcode. Check [Hugo docs](https://gohugo.io/variables/page/) to learn more about which parameters are available to use.
@ -465,7 +465,7 @@ The `where` and `value` values are used in the following query `where .Site.Regu
{{<listlimit=2>}}
**Example #2:**
**例 2:**
```md
{{</* list title="Samples" cardView=true limit=5 where="Type" value="sample" */>}}
@ -475,11 +475,11 @@ The `where` and `value` values are used in the following query `where .Site.Regu
<br/><br/><br/>
## LTR/RTL
## 文字书写方向
`ltr`and `rtl` allows you to mix your contents. Many RTL language users want to include parts of the content in LTR. Using this shortcode will let you do so, and by leveraging `%` as the outer-most dilemeter in the shortcode [Hugo shortcodes](https://gohugo.io/content-management/shortcodes/#shortcodes-with-markdown), any markdown inside will be rendered normally.
@ -499,20 +499,20 @@ The `where` and `value` values are used in the following query `where .Site.Regu
<br/><br/><br/>
## Markdown Importer
## Markdown 导入
This shortcode allows you to import markdown files from external sources. This is useful for including content from other repositories or websites without having to copy and paste the content.
@ -526,13 +526,13 @@ This shortcode allows you to import markdown files from external sources. This i
## Mermaid
`mermaid`allows you to draw detailed diagrams and visualisations using text. It uses Mermaid under the hood and supports a wide variety of diagrams, charts and other output formats.
`swatches`outputs a set of up to three different colors to showcase color elements like a color palette. This shortcode takes the `HEX` codes of each color and creates the visual elements for each.
The `timeline` creates a visual timeline that can be used in different use-cases, e.g. professional experience, a project's achievements, etc. The `timeline` shortcode relies on the `timelineItem` sub-shortcode to define each item within the main timeline. Each item can have the following properties.
| `icon` | the icon to be used in the timeline visuals. |
| `header` | header for each entry |
| `badge` | text to place within the top right badge |
| `subheader` | entry's subheader |
| `icon` | 要在时间线中使用的图标。 |
| `header` | 每个条目的标题 |
| `badge` | 放置在右上角徽章内的文本 |
| `subheader` | 每个条目的副标题 |
<!-- prettier-ignore-end -->
**Example:**
**例如：**
```md
{{</* timeline */>}}
@ -654,26 +653,26 @@ With other shortcodes
## TypeIt
[TypeIt](https://www.typeitjs.com) is the most versatile JavaScript tool for creating typewriter effects on the planet. With a straightforward configuration, it allows you to type single or multiple strings that break lines, delete & replace each other, and it even handles strings that contain complex HTML.
[TypeIt](https://www.typeitjs.com) 是用于创建打字机效果的最通用的 JavaScript 工具。通过简单的配置，它允许您键入单个或多个断行、删除和相互替换的字符串，甚至可以处理包含复杂 HTML 的字符串。
Blowfish implements a sub-set of TypeIt features using a `shortcode`. Write your text within the `typeit` shortcode and use the following parameters to configure the behavior you want.
| `tag` | [String] `html` tag that will be used to render the strings. |
| `classList` | [String] List of `css` classes to apply to the `html` element. |
| `initialString` | [String] Initial string that will appear written and will be replaced. |
| `speed` | [number] Typing speed, measured in milliseconds between each step. |
| `lifeLike` | [boolean] Makes the typing pace irregular, as if a real person is doing it. |
| `startDelay` | [number] The amount of time before the plugin begins typing after being initialized. |
| `breakLines` | [boolean] Whether multiple strings are printed on top of each other (true), or if they're deleted and replaced by each other (false). |
| `waitUntilVisible` | [boolean] Determines if the instance will begin when loaded or only when the target element becomes visible in the viewport. The default is`true` |
| `loop` | [boolean] Whether your strings will continuously loop after completing |
A shortcut to embed youtube videos using the [lite-youtube-embed](https://github.com/paulirish/lite-youtube-embed) library. This library is a lightweight alternative to the standard youtube embeds, and it's designed to be faster and more efficient.
Aphcity