docs: update docs for admonitions

2026-01-30 16:31:52 +01:00 · 2025-12-21 22:06:47 +08:00
parent accf29dea3
commit 1fc6058426
8 changed files with 135 additions and 22 deletions
--- a/exampleSite/content/docs/shortcodes/index.it.md
+++ b/exampleSite/content/docs/shortcodes/index.it.md
@@ -64,6 +64,36 @@ This is an error!

 <br/><br/><br/>

+## Admonition
+
+Admonitions allow you to insert eye-catching callout boxes in your content.
+
+Admonitions serve a similar purpose as the alert shortcode but are implemented via Hugo render hooks. The key difference is syntax: admonitions use Markdown syntax, making them more portable across different platforms, whereas shortcodes are specific to Hugo. The syntax resembles GitHub alerts:
+
+```md
+> [!NOTE]
+> A Note type admonition.
+
+> [!TIP]+ Custom Title
+> A collapsible admonition with custom title.
+```
+
+> [!NOTE]
+> A Note type admonition.
+
+> [!TIP]+ Custom Title
+> A collapsible admonition with custom title.
+
+The alert sign (`+` or `-`) is optional to control whether the admonition is folded or not. Note that alert sign is only compatible in Obsidian.
+
+> [!INFO]- Supported types
+> Valid admonition types include [GitHub alert types](https://github.blog/changelog/2023-12-14-new-markdown-extension-alerts-provide-distinctive-styling-for-significant-content/) and [Obsidian callout types](https://help.obsidian.md/callouts). The types are case-insensitive.
+>
+> **GitHub types:** `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`  
+> **Obsidian types:** `note`, `abstract`, `info`, `todo`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, `quote`
+
+<br/><br/><br/>
+
 ## Article

 `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.*
--- a/exampleSite/content/docs/shortcodes/index.ja.md
+++ b/exampleSite/content/docs/shortcodes/index.ja.md
@@ -64,6 +64,36 @@ Twitter で私を[フォロー](https://twitter.com/nunocoracao)するのを忘

 <br/><br/><br/>

+## Admonition
+
+Admonitions は、文書内で読者の注意を引くための強調表示を挿入するための機能です。
+
+Admonitions は alert ショートコードと同様の目的を持ちますが、Hugo の render hooks を用いて実装されています。両者の主な違いは構文にあります。admonitions は Markdown 構文を使用するため、異なるプラットフォーム間でも扱いやすく、一方、ショートコードは Hugo 固有の仕組みです。構文は GitHub の alerts に近い形式です。
+
+```md
+> [!NOTE]
+> NOTE タイプの表示例。
+
+> [!TIP]+ カスタムタイトル
+> タイトルを指定した折りたたみ可能な表示例。
+```
+
+> [!NOTE]
+> NOTE タイプの表示例。
+
+> [!TIP]+ カスタムタイトル
+> タイトルを指定した折りたたみ可能な表示例。
+
+記号（`+` または `-`）は任意で、表示を折りたたむかどうかを制御します。なお、この記号は Obsidian のみ対応しています。
+
+> [!INFO]- 対応しているタイプ
+> 使用可能なタイプには、[GitHub alert タイプ](https://github.blog/changelog/2023-12-14-new-markdown-extension-alerts-provide-distinctive-styling-for-significant-content/) および [Obsidian callout タイプ](https://help.obsidian.md/callouts) が含まれます。タイプ名は大文字・小文字を区別しません。
+>
+> **GitHub タイプ：** `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`  
+> **Obsidian タイプ：** `note`, `abstract`, `info`, `todo`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, `quote`
+
+<br/><br/><br/>
+
 ## 記事

 `Article` は、1つの記事を Markdown ファイルに埋め込みます。埋め込むファイルへの `link` は、埋め込むファイルの `.RelPermalink` である必要があります。ショートコードは、親を参照している場合は何も表示しないことに注意してください。*注: Blowfish (/blowfish/ など) のようなサブフォルダでウェブサイトを実行している場合は、そのパスをリンクに含めてください。*
--- a/exampleSite/content/docs/shortcodes/index.md
+++ b/exampleSite/content/docs/shortcodes/index.md
@@ -64,9 +64,39 @@ This is an error!

 <br/><br/><br/>

+## Admonition
+
+Admonitions allow you to insert eye-catching callout boxes in your content.
+
+Admonitions serve a similar purpose as the alert shortcode but are implemented via Hugo render hooks. The key difference is syntax: admonitions use Markdown syntax, making them more portable across different platforms, whereas shortcodes are specific to Hugo. The syntax resembles GitHub alerts:
+
+```md
+> [!NOTE]
+> A Note type admonition.
+
+> [!TIP]+ Custom Title
+> A collapsible admonition with custom title.
+```
+
+> [!NOTE]
+> A Note type admonition.
+
+> [!TIP]+ Custom Title
+> A collapsible admonition with custom title.
+
+The alert sign (`+` or `-`) is optional to control whether the admonition is folded or not. Note that alert sign is only compatible in Obsidian.
+
+> [!INFO]- Supported types
+> Valid admonition types include [GitHub alert types](https://github.blog/changelog/2023-12-14-new-markdown-extension-alerts-provide-distinctive-styling-for-significant-content/) and [Obsidian callout types](https://help.obsidian.md/callouts). The types are case-insensitive.
+>
+> **GitHub types:** `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`  
+> **Obsidian types:** `note`, `abstract`, `info`, `todo`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, `quote`
+
+<br/><br/><br/>
+
 ## Article

-`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.*
+`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._

 <!-- prettier-ignore-start -->
 | Parameter | Description                                              |
@@ -202,16 +232,15 @@ This shortcode is for importing code from external sources easily without copyin
 | `startLine` | **Optional** The line number to start the import from.    |
 | `endLine` | **Optional** The line number to end the import at.        |

-
 <!-- prettier-ignore-end -->

-
 **Example:**

 ```md
 {{</* codeimporter url="https://raw.githubusercontent.com/nunocoracao/blowfish/main/layouts/shortcodes/mdimporter.html" type="go" */>}}

 ```
+
 {{< codeimporter url="https://raw.githubusercontent.com/nunocoracao/blowfish/main/layouts/shortcodes/mdimporter.html" type="go" >}}

 ```md
@@ -221,7 +250,6 @@ This shortcode is for importing code from external sources easily without copyin

 {{< codeimporter url="https://raw.githubusercontent.com/nunocoracao/blowfish/main/config/_default/hugo.toml" type="toml" startLine="11" endLine="18">}}

-
 <br/><br/>

 ## Codeberg Card
@@ -239,6 +267,7 @@ This shortcode is for importing code from external sources easily without copyin
 ```md
 {{</* codeberg repo="forgejo/forgejo" */>}}
 ```
+
 {{< codeberg repo="forgejo/forgejo" >}}

 <br/><br/><br/>
@@ -304,6 +333,7 @@ Blowfish also supports automatic conversion of images included using standard Ma
 ```md
 {{</* forgejo server="https://v11.next.forgejo.org" repo="a/mastodon" */>}}
 ```
+
 {{< forgejo server="https://v11.next.forgejo.org" repo="a/mastodon" >}}

 <br/><br/><br/>
@@ -340,7 +370,6 @@ In order to add images to the gallery, use `img` tags for each image and add `cl

 <br/><br/><br/>

-
 **Example 2: responsive gallery**

 ```md
@@ -411,6 +440,7 @@ In order to add images to the gallery, use `img` tags for each image and add `cl
 ```md
 {{</* gitea server="https://git.fsfe.org" repo="FSFE/fsfe-website" */>}}
 ```
+
 {{< gitea server="https://git.fsfe.org" repo="FSFE/fsfe-website" >}}

 <br/><br/><br/>
@@ -438,7 +468,7 @@ In order to add images to the gallery, use `img` tags for each image and add `cl

 ## GitLab Card

-`gitlab` allows you to quickly link a GitLab Project (GitLab's jargon for repo). 
+`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.
@@ -531,13 +561,10 @@ Check out the [mathematical notation samples]({{< ref "mathematical-notation" >}

 <br/><br/><br/>

-
 ## Keyword

-
 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.

-
 <!-- prettier-ignore-start -->
 | Parameter | Description                             |
 | --------- | --------------------------------------- |
@@ -552,7 +579,7 @@ The input is written in Markdown so you can format it however you please.
 {{</* keyword */>}} *Super* skill {{</* /keyword */>}}
 ```

-{{< keyword >}} *Super* skill {{< /keyword >}}
+{{< keyword >}} _Super_ skill {{< /keyword >}}

 **Example2 :**

@@ -569,7 +596,7 @@ The input is written in Markdown so you can format it however you please.
 {{< keyword icon="github" >}} Lorem ipsum dolor {{< /keyword >}}
 {{< keyword icon="code" >}} **Important** skill {{< /keyword >}}
 {{< /keywordList >}}
-{{< keyword >}} *Standalone* skill {{< /keyword >}}
+{{< keyword >}} _Standalone_ skill {{< /keyword >}}

 <br/><br/><br/>

@@ -589,7 +616,7 @@ When life gives you lemons, make lemonade.
 When life gives you lemons, make lemonade.
 {{< /lead >}}

-<br/><br/><br/> 
+<br/><br/><br/>

 ## List

@@ -628,7 +655,7 @@ The `where` and `value` values are used in the following query `where .Site.Regu

 <br/><br/><br/>

-## LTR/RTL 
+## 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.

@@ -661,10 +688,8 @@ This shortcode allows you to import markdown files from external sources. This i
 | --------- | ------------------------------------------------------- |
 | `url`     | **Required** URL to an externally hosted markdown file. |

-
 <!-- prettier-ignore-end -->

-
 **Example:**

 ```md
@@ -674,7 +699,6 @@ This shortcode allows you to import markdown files from external sources. This i

 {{< mdimporter url="https://raw.githubusercontent.com/nunocoracao/nunocoracao/master/README.md" >}}

-
 <br/><br/>

 ## Mermaid
@@ -724,7 +748,6 @@ You can see some additional Mermaid examples on the [diagrams and flowcharts sam

 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.

-
 <!-- prettier-ignore-start -->
 | Parameter   | Description                                  |
 | ----------- | -------------------------------------------- |
@@ -775,14 +798,12 @@ With other shortcodes
 {{</* /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
 <ul>
@@ -809,7 +830,6 @@ With other shortcodes
 {{</ timelineItem >}}
 {{</ timeline >}}

-
 <br/><br/><br/>

 ## TypeIt
@@ -891,7 +911,6 @@ consectetur adipiscing elit.
 "Toto, I've a feeling we're not in Kansas anymore." The Wizard of Oz (1939)
 {{< /typeit >}}

-
 <br/><br/><br/>

 ## Youtube Lite
--- a/exampleSite/content/docs/shortcodes/index.zh-cn.md
+++ b/exampleSite/content/docs/shortcodes/index.zh-cn.md
@@ -64,6 +64,36 @@ This is an error!

 <br/><br/><br/>

+## Admonition
+
+Admonition 用于在内容中插入醒目提示。
+
+Admonition 的用途与 alert shortcode 类似，但其实现方式是通过 Hugo 的 render hooks。两者的关键区别在于语法：admonition 使用 Markdown 语法，因此在不同平台之间具有更好的可移植性；而 shortcode 是 Hugo 专有的。其语法类似 GitHub 的 alerts：
+
+```md
+> [!NOTE]
+> 一个 NOTE 类型的提示块。
+
+> [!TIP]+ 自定义标题
+> 一个带有自定义标题的可折叠提示块。
+```
+
+> [!NOTE]
+> 一个 NOTE 类型的提示块。
+
+> [!TIP]+ 自定义标题
+> 一个带有自定义标题的可折叠提示块。
+
+提示符号（`+` 或 `-`）是可选的，用于控制提示块是否默认折叠。请注意，该提示符号仅在 Obsidian 中兼容。
+
+> [!INFO]- 支持的类型
+> 可用的 admonition 类型包括 [GitHub alert 类型](https://github.blog/changelog/2023-12-14-new-markdown-extension-alerts-provide-distinctive-styling-for-significant-content/) 和 [Obsidian callout 类型](https://help.obsidian.md/callouts)。类型名称不区分大小写。
+>
+> **GitHub 类型：** `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`  
+> **Obsidian 类型：** `note`, `abstract`, `info`, `todo`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, `quote`
+
+<br/><br/><br/>
+
 ## Article

 `Article` 将把一篇文章嵌入到一个 markdown 文件中。 参数中的 `link`应该是要嵌入的文件的 `.RelPermalink`。请注意，如果简码引用其父级文件，则它不会显示任何内容。 *注意：如果您在 Blowfish（即 /blowfish/）等子文件夹中运行网站，请在链接中包含该路径。*