github/hugo-geekblog
0
0
Fork 0
mirror of https://github.com/thegeeklab/hugo-geekblog.git synced 2024-11-21 20:50:40 +00:00
Code Issues Projects Releases Wiki Activity

docs: use a propertylist to document shortcode attributes (#456)

Browse Source
This commit is contained in:
Robert Kaussow 2023-10-27 21:58:03 +02:00 committed by GitHub
parent e7a3759f0a
commit 72c23c9184
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 223 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

211
exampleSite/content/posts/advanced/shortcodes.md
View File

@ -21,12 +21,22 @@ The theme bundles some handy shortcodes that tries to cover common situations.
Buttons are styled links that can lead to local page or external link. Buttons are styled links that can lead to local page or external link.
### Usage
<!-- prettier-ignore --> <!-- prettier-ignore -->
```tpl ```tpl
{{</* button relref="/" [class="...", size="large|regular"] */>}}Get Home{{</* /button */>}} {{</* button relref="/" [class="...", size="large|regular"] */>}}Get Home{{</* /button */>}}
{{</* button href="https://github.com/thegeeklab/hugo-geekblog" */>}}Contribute{{</* /button */>}} {{</* button href="https://github.com/thegeeklab/hugo-geekblog" */>}}Contribute{{</* /button */>}}
``` ```
#### Attributes
<!-- prettier-ignore-start -->
<!-- spellchecker-disable -->
{{< propertylist name=shortcode-buttons sort=name order=asc >}}
<!-- spellchecker-enable -->
<!-- prettier-ignore-end -->
### Example ### Example
<!-- prettier-ignore-start --> <!-- prettier-ignore-start -->
@ -41,12 +51,6 @@ Buttons are styled links that can lead to local page or external link.
The Columns shortcode can be used to organize content side-by-side (horizontally) for better readability. The Columns shortcode can be used to organize content side-by-side (horizontally) for better readability.
### Attributes
| Name | Description | default |
| --------------- | ------------------------------------------------ | ------- |
| size (optional) | size of the first column (small\|regular\|large) | regular |
### Usage ### Usage
<!-- prettier-ignore --> <!-- prettier-ignore -->
@ -67,6 +71,14 @@ Dolor sit, sumo unique argument um no ...
{{</* /columns */>}} {{</* /columns */>}}
``` ```
#### Attributes
<!-- prettier-ignore-start -->
<!-- spellchecker-disable -->
{{< propertylist name=shortcode-columns sort=name order=asc >}}
<!-- spellchecker-enable -->
<!-- prettier-ignore-end -->
### Example ### Example
{{< columns >}} {{< columns >}}
@ -99,9 +111,11 @@ copious quo ad. Stet probates in duo.
Emoji can be enabled in a Hugo project in a number of ways. Emoji can be enabled in a Hugo project in a number of ways.
The [emojify](https://gohugo.io/functions/emojify/) function can be called directly in templates or [Inline Shortcodes](https://gohugo.io/templates/shortcode-templates/#inline-shortcodes). To enable emoji globally, set `enableEmoji` to `true` in your site's [configuration](https://gohugo.io/getting-started/configuration/) and then you can type emoji shorthand codes directly in content files: The [emojify](https://gohugo.io/functions/emojify/) function can be called directly in templates or [Inline Shortcodes](https://gohugo.io/templates/shortcode-templates/#inline-shortcodes). To enable emoji globally, set `enableEmoji` to `true` in your site's [configuration](https://gohugo.io/getting-started/configuration/) and then you can type emoji shorthand codes directly in content files.
| Result | Inline | Shortcode | ### Example
| Output | Inline | Shortcode |
| --------------------------------- | ----------------- | --------------------------------------- | | --------------------------------- | ----------------- | --------------------------------------- |
| {{< emojify ":see_no_evil:" >}} | `:see_no_evil:` | `{{</* emojify ":see_no_evil:" */>}}` | | {{< emojify ":see_no_evil:" >}} | `:see_no_evil:` | `{{</* emojify ":see_no_evil:" */>}}` |
| {{< emojify ":hear_no_evil:" >}} | `:hear_no_evil:` | `{{</* emojify ":hear_no_evil:" */>}}` | | {{< emojify ":hear_no_evil:" >}} | `:hear_no_evil:` | `{{</* emojify ":hear_no_evil:" */>}}` |
@ -110,58 +124,55 @@ The [emojify](https://gohugo.io/functions/emojify/) function can be called direc
The [Emoji cheat sheet](https://github.com/ikatyang/emoji-cheat-sheet) is a useful reference for emoji shorthand codes. The [Emoji cheat sheet](https://github.com/ikatyang/emoji-cheat-sheet) is a useful reference for emoji shorthand codes.
{{< hint type=note >}} {{< hint type=note >}}
**Info**\
The above steps enable Unicode Standard emoji characters and sequences in Hugo, however the rendering of these glyphs depends on the browser and the platform. To style the emoji you can either use a third party emoji font or a font stack. The above steps enable Unicode Standard emoji characters and sequences in Hugo, however the rendering of these glyphs depends on the browser and the platform. To style the emoji you can either use a third party emoji font or a font stack.
{{< /hint >}} {{< /hint >}}
**Styling:** <!-- prettier-ignore-start -->
<!-- spellchecker-disable --> <!-- spellchecker-disable -->
<!-- prettier-ignore -->
{{< highlight html "linenos=table" >}} {{< highlight html "linenos=table" >}}
.emoji { .emoji {
font-family: Apple Color Emoji, Segoe UI Emoji, NotoColorEmoji, Segoe UI Symbol, Android Emoji, EmojiSymbols; font-family: Apple Color Emoji, Segoe UI Emoji, NotoColorEmoji, Segoe UI Symbol, Android Emoji, EmojiSymbols;
} }
{{< /highlight >}} {{< /highlight >}}
<!-- spellchecker-enable --> <!-- spellchecker-enable -->
<!-- prettier-ignore-end -->
## Expand ## Expand
Expand shortcode can help to decrease clutter on screen by hiding part of text. Expand content by clicking on it. Expand shortcode can help to decrease clutter on screen by hiding part of text. Expand content by clicking on it.
### Example ### Usage
#### Default
<!-- prettier-ignore -->
```tpl ```tpl
{{</* expand */>}} {{</* expand */>}}
## Markdown content ### Markdown content
Dolor sit, sumo unique ... Dolor sit, sumo unique ...
{{</* /expand */>}} {{</* /expand */>}}
``` ```
It is also possible to use a custom label and symbol.
<!-- prettier-ignore-start -->
```tpl
{{</* expand "Custom Label" "..." */>}}
### More markdown
Dolor sit, sumo unique ...
{{</* /expand */>}}
```
### Example
{{< expand >}} {{< expand >}}
##### Markdown content #### Markdown content
Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re.
{{< /expand >}} {{< /expand >}}
#### With Custom Label
<!-- prettier-ignore -->
```tpl
{{</* expand "Custom Label" "..." */>}}
## Markdown content
Dolor sit, sumo unique ...
{{</* /expand */>}}
```
{{< expand "Custom Label" "..." >}} {{< expand "Custom Label" "..." >}}
##### More markdown #### More markdown
Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates
investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts
@ -173,19 +184,11 @@ copious quo ad. Stet probates in duo.
Hint shortcode can be used as hint/alerts/notification block. Hint shortcode can be used as hint/alerts/notification block.
### Attributes
| Name | Description | default |
| ---------------- | --------------------------------------------------------------------------------------- | --------- |
| type | hint type | note |
| icon (optional) | custom icon to use, need to be an icon from an [SVG sprite](/posts/features/icon-sets/) | undefined |
| title (optional) | hint title | undefined |
### Usage ### Usage
<!-- prettier-ignore-start --> <!-- prettier-ignore-start -->
```tpl ```tpl
{{</* hint type="note|tip|important|caution|warning" [icon="gblog_github" title="GitHub"] */>}} {{</* hint type=[note|tip|important|caution|warning] (icon=gblog_github) (title=GitHub) */>}}
**Markdown content**\ **Markdown content**\
Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
Ornateness bland it ex enc, est yeti am bongo detract re. Ornateness bland it ex enc, est yeti am bongo detract re.
@ -193,6 +196,14 @@ Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclima
``` ```
<!-- prettier-ignore-end --> <!-- prettier-ignore-end -->
#### Attributes
<!-- prettier-ignore-start -->
<!-- spellchecker-disable -->
{{< propertylist name=shortcode-hints sort=name order=asc >}}
<!-- spellchecker-enable -->
<!-- prettier-ignore-end -->
### Example ### Example
{{< hint type=note >}} {{< hint type=note >}}
@ -243,14 +254,17 @@ Ornateness bland it ex enc, est yeti am bongo detract re.
Simple shortcode to include icons from SVG sprites outside of menus. Simple shortcode to include icons from SVG sprites outside of menus.
<!-- prettier-ignore --> ### Usage
<!-- prettier-ignore-start -->
```tpl ```tpl
{{</* icon "thumbs-up" */>}} {{</* icon "thumbs-up" */>}}
``` ```
<!-- prettier-ignore-end -->
### Example ### Example
| Result | Usage | | Output | Code |
| -------------------------- | -------------------------------- | | -------------------------- | -------------------------------- |
| {{< icon "thumbs-up" >}} | `{{</* icon "thumbs-up" */>}}` | | {{< icon "thumbs-up" >}} | `{{</* icon "thumbs-up" */>}}` |
| {{< icon "thumbs-down" >}} | `{{</* icon "thumbs-down" */>}}` | | {{< icon "thumbs-down" >}} | `{{</* icon "thumbs-down" */>}}` |
@ -262,7 +276,9 @@ Simple shortcode to include icons from SVG sprites outside of menus.
Tabs let you organize content by context, for example installation instructions for each supported platform. Tabs let you organize content by context, for example installation instructions for each supported platform.
<!-- prettier-ignore --> ### Usage
<!-- prettier-ignore-start -->
```tpl ```tpl
{{</* tabs "uniqueid" */>}} {{</* tabs "uniqueid" */>}}
{{</* tab "macOS" */>}} # macOS Content {{</* /tab */>}} {{</* tab "macOS" */>}} # macOS Content {{</* /tab */>}}
@ -270,6 +286,7 @@ Tabs let you organize content by context, for example installation instructions
{{</* tab "Windows" */>}} # Windows Content {{</* /tab */>}} {{</* tab "Windows" */>}} # Windows Content {{</* /tab */>}}
{{</* /tabs */>}} {{</* /tabs */>}}
``` ```
<!-- prettier-ignore-end -->
### Example ### Example
@ -314,14 +331,6 @@ prompts feud gait, quid exercise emeritus bis e. In pro quints consequent.
Boxes can be used to create a simple grid. Boxes can be used to create a simple grid.
### Attributes
| Name | Description | default |
| ---------------- | ----------------------------------------------------------------------------------- | --------- |
| size | size of each box (regular\|large) | regular |
| icon (optional) | title bar icon, need to be an icon from an [SVG sprite](/posts/features/icon-sets/) | undefined |
| title (optional) | title bar text | undefined |
### Usage ### Usage
<!-- prettier-ignore --> <!-- prettier-ignore -->
@ -334,6 +343,14 @@ Boxes can be used to create a simple grid.
{{</* /boxes */>}} {{</* /boxes */>}}
``` ```
#### Attributes
<!-- prettier-ignore-start -->
<!-- spellchecker-disable -->
{{< propertylist name=shortcode-boxes sort=name order=asc >}}
<!-- spellchecker-enable -->
<!-- prettier-ignore-end -->
### Example ### Example
<!-- prettier-ignore-start --> <!-- prettier-ignore-start -->
@ -354,13 +371,11 @@ Boxes can be used to create a simple grid.
[Mermaid](https://mermaidjs.github.io/) is library for generating SVG charts and diagrams from text. [Mermaid](https://mermaidjs.github.io/) is library for generating SVG charts and diagrams from text.
<!--more--> ### Usage
### Example
<!-- prettier-ignore --> <!-- prettier-ignore -->
```tpl ```tpl
{{</*/* mermaid class="text-center" */*/>}} {{</* mermaid class="text-center" */>}}
sequenceDiagram sequenceDiagram
Alice->>Bob: Hello Bob, how are you? Alice->>Bob: Hello Bob, how are you?
alt is sick alt is sick
@ -371,9 +386,19 @@ sequenceDiagram
opt Extra response opt Extra response
Bob->>Alice: Thanks for asking Bob->>Alice: Thanks for asking
end end
{{</*/* /mermaid */*/>}} {{</* /mermaid */>}}
``` ```
#### Attributes
<!-- prettier-ignore-start -->
<!-- spellchecker-disable -->
{{< propertylist name=shortcode-mermaid sort=name order=asc >}}
<!-- spellchecker-enable -->
<!-- prettier-ignore-end -->
### Example
<!-- spellchecker-disable --> <!-- spellchecker-disable -->
<!-- prettier-ignore --> <!-- prettier-ignore -->
{{< mermaid class="text-center" >}} {{< mermaid class="text-center" >}}
@ -389,6 +414,8 @@ sequenceDiagram
end end
{{< /mermaid >}} {{< /mermaid >}}
<!-- spellchecker-enable -->
As an alternative to shortcodes, code blocks can be used for markdown as well. As an alternative to shortcodes, code blocks can be used for markdown as well.
{{< columns >}} {{< columns >}}
@ -424,14 +451,24 @@ C -->|Two| E[Result 2]
[KaTeX](https://katex.org/) shortcode let you render math typesetting in markdown document. [KaTeX](https://katex.org/) shortcode let you render math typesetting in markdown document.
### Example ### Usage
```latex ```latex
{{</*/* katex [display] [class="text-center"] */*/>}} {{</* katex [display] [class="text-center"] */>}}
f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
{{</*/* /katex */*/>}} {{</* /katex */>}}
``` ```
#### Attributes
<!-- prettier-ignore-start -->
<!-- spellchecker-disable -->
{{< propertylist name=shortcode-katex sort=name order=asc >}}
<!-- spellchecker-enable -->
<!-- prettier-ignore-end -->
### Example
<!-- spellchecker-disable --> <!-- spellchecker-disable -->
<!-- prettier-ignore --> <!-- prettier-ignore -->
{{< katex display >}} {{< katex display >}}
@ -440,27 +477,23 @@ f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
<!-- spellchecker-enable --> <!-- spellchecker-enable -->
KaTeX can be used inline, for example {{< katex >}}\pi(x){{< /katex >}} or used with the `display` parameter (see above). KaTeX can be used inline, for example {{< katex >}}\pi(x){{< /katex >}} or used with the `display` parameter as above.
Text continues here.
## Progress ## Progress
### Attributes
| Name | Description | default |
| ---------------- | -------------------------------------------------------------------------------- | --------- |
| value | progress value (0-100) | 0 |
| label | value to display | value |
| icon (optional) | icon to use, need to be an icon from an [SVG sprite](/posts/features/icon-sets/) | undefined |
| title (optional) | progress title | undefined |
### Usage ### Usage
<!-- prettier-ignore-start --> <!-- prettier-ignore -->
```tpl ```tpl
{{</* progress title=Eating value=65 icon=gblog_heart */>}} {{</* progress title=Eating value=65 icon=gblog_heart */>}}
``` ```
#### Attributes
<!-- prettier-ignore-start -->
<!-- spellchecker-disable -->
{{< propertylist name=shortcode-progress sort=name order=asc >}}
<!-- spellchecker-enable -->
<!-- prettier-ignore-end --> <!-- prettier-ignore-end -->
### Example ### Example
@ -470,3 +503,39 @@ Text continues here.
{{< progress title=Eating value=65 icon=gblog_heart >}} {{< progress title=Eating value=65 icon=gblog_heart >}}
<!-- spellchecker-enable --> <!-- spellchecker-enable -->
<!-- prettier-ignore-end --> <!-- prettier-ignore-end -->
## Properties
The property list shortcode creates a custom HTML description list that can be used to display properties or variables and general dependent information. The shortcode requires a data file in `data/properties/`, e.g. `data/properties/demo.yaml`.
### Usage
<!-- prettier-ignore-start -->
```tpl
{{</* propertylist name=demo (sort=name) (order=[asc|desc]) */>}}
```
<!-- prettier-ignore-end -->
The supported attributes can be taken from the following example:
<!-- prettier-ignore-start -->
<!-- spellchecker-disable -->
{{< include file="/data/properties/demo.yaml" language="Yaml" options="linenos=table" >}}
<!-- spellchecker-enable -->
<!-- prettier-ignore-end -->
#### Attributes
<!-- prettier-ignore-start -->
<!-- spellchecker-disable -->
{{< propertylist name=shortcode-buttons sort=name order=asc >}}
<!-- spellchecker-enable -->
<!-- prettier-ignore-end -->
### Example
<!-- prettier-ignore-start -->
<!-- spellchecker-disable -->
{{< propertylist name=demo sort=name order=asc >}}
<!-- spellchecker-enable -->
<!-- prettier-ignore-end -->

15
exampleSite/data/properties/shortcode-boxes.yaml Normal file
View File

@ -0,0 +1,15 @@
---
properties:
- name: size
type: string
description: Size of each box. Supported values are `regular|large`.
required: false
devaultValue: regular
- name: icon
type: string
description: Icon to use. The value need to be an icon from an [SVG sprite](/features/icon-sets/).
required: false
- name: title
type: string
description: Title text of the hint.
required: false

19
exampleSite/data/properties/shortcode-buttons.yaml Normal file
View File

@ -0,0 +1,19 @@
---
properties:
- name: href
type: string
description: The URL to use as target of the button.
required: false
- name: relref
type: string
description: Executes the [relref](https://gohugo.io/functions/urls/relref/) Hugo function to resolve the relative permalink of the specified page. The result is set as the target of the button.
required: false
- name: class
type: list
description: List of space-separated CSS class names to apply.
required: false
- name: size
type: string
description: Preset of different button sizes. Supported values are `regular|large`.
required: false
devaultValue: regular

7
exampleSite/data/properties/shortcode-columns.yaml Normal file
View File

@ -0,0 +1,7 @@
---
properties:
- name: size
type: string
description: Preset of different sizes for the _first_ column. Supported values are `small|regular|large`.
required: false
defaultValue: regular

15
exampleSite/data/properties/shortcode-hints.yaml Normal file
View File

@ -0,0 +1,15 @@
---
properties:
- name: type
type: string
description: Type of the hint. Supported values are `note|tip|important|caution|warning`.
required: false
defaultValue: note
- name: icon
type: string
description: Icon to use. The value need to be an icon from an [SVG sprite](/features/icon-sets/).
required: false
- name: title
type: string
description: Title text of the hint.
required: false

6
exampleSite/data/properties/shortcode-katex.yaml Normal file
View File

@ -0,0 +1,6 @@
---
properties:
- name: class
type: list
description: List of space-separated CSS class names to apply.
required: false

6
exampleSite/data/properties/shortcode-mermaid.yaml Normal file
View File

@ -0,0 +1,6 @@
---
properties:
- name: class
type: list
description: List of space-separated CSS class names to apply.
required: false

15
exampleSite/data/properties/shortcode-progress.yaml Normal file
View File

@ -0,0 +1,15 @@
---
properties:
- name: value
type: integer
description: Progress value.
required: false
defaultValue: 0
- name: icon
type: string
description: Icon to use. The value need to be an icon from an [SVG sprite](/features/icon-sets/).
required: false
- name: title
type: string
description: Title text of the progress bar.
required: false