dbrun/blowfish
1
0
Fork 0
mirror of https://github.com/nunocoracao/blowfish.git synced 2026-01-30 15:31:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update docs for admonitions

Browse Source
This commit is contained in:
ZhenShuo Leo
2025-12-21 22:06:47 +08:00
parent accf29dea3
commit 1fc6058426
8 changed files with 135 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
exampleSite/content/docs/shortcodes/index.md
+40 -21
View File
@@ -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