From 72c23c91845a38278b553f28642165821d054d6b Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Fri, 27 Oct 2023 21:58:03 +0200 Subject: [PATCH] docs: use a propertylist to document shortcode attributes (#456) --- .../content/posts/advanced/shortcodes.md | 205 ++++++++++++------ .../data/properties/shortcode-boxes.yaml | 15 ++ .../data/properties/shortcode-buttons.yaml | 19 ++ .../data/properties/shortcode-columns.yaml | 7 + .../data/properties/shortcode-hints.yaml | 15 ++ .../data/properties/shortcode-katex.yaml | 6 + .../data/properties/shortcode-mermaid.yaml | 6 + .../data/properties/shortcode-progress.yaml | 15 ++ 8 files changed, 220 insertions(+), 68 deletions(-) create mode 100644 exampleSite/data/properties/shortcode-boxes.yaml create mode 100644 exampleSite/data/properties/shortcode-buttons.yaml create mode 100644 exampleSite/data/properties/shortcode-columns.yaml create mode 100644 exampleSite/data/properties/shortcode-hints.yaml create mode 100644 exampleSite/data/properties/shortcode-katex.yaml create mode 100644 exampleSite/data/properties/shortcode-mermaid.yaml create mode 100644 exampleSite/data/properties/shortcode-progress.yaml diff --git a/exampleSite/content/posts/advanced/shortcodes.md b/exampleSite/content/posts/advanced/shortcodes.md index 838589e..0283ee7 100644 --- a/exampleSite/content/posts/advanced/shortcodes.md +++ b/exampleSite/content/posts/advanced/shortcodes.md @@ -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. +### Usage + ```tpl {{}}Get Home{{}} {{}}Contribute{{}} ``` +#### Attributes + + + +{{< propertylist name=shortcode-buttons sort=name order=asc >}} + + + ### Example @@ -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. -### Attributes - -| Name | Description | default | -| --------------- | ------------------------------------------------ | ------- | -| size (optional) | size of the first column (small\|regular\|large) | regular | - ### Usage @@ -67,6 +71,14 @@ Dolor sit, sumo unique argument um no ... {{}} ``` +#### Attributes + + + +{{< propertylist name=shortcode-columns sort=name order=asc >}} + + + ### Example {{< 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. -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 ":hear_no_evil:" >}} | `: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. {{< 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. {{< /hint >}} -**Styling:** - + - {{< highlight html "linenos=table" >}} .emoji { font-family: Apple Color Emoji, Segoe UI Emoji, NotoColorEmoji, Segoe UI Symbol, Android Emoji, EmojiSymbols; } {{< /highlight >}} - + ## Expand Expand shortcode can help to decrease clutter on screen by hiding part of text. Expand content by clicking on it. -### Example - -#### Default +### Usage - ```tpl {{}} -## Markdown content +### Markdown content Dolor sit, sumo unique ... {{}} ``` -{{< expand >}} - -##### 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. -{{< /expand >}} +It is also possible to use a custom label and symbol. -#### With Custom Label + - ```tpl {{}} -## Markdown content +### More markdown Dolor sit, sumo unique ... {{}} ``` +### Example + +{{< expand >}} + +#### 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. +{{< /expand >}} + {{< expand "Custom Label" "..." >}} -##### More markdown +#### More markdown 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 @@ -173,19 +184,11 @@ copious quo ad. Stet probates in duo. 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 ```tpl -{{}} +{{}} **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. @@ -193,6 +196,14 @@ Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclima ``` +#### Attributes + + + +{{< propertylist name=shortcode-hints sort=name order=asc >}} + + + ### Example {{< 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. - +### Usage + + ```tpl {{}} ``` + ### Example -| Result | Usage | +| Output | Code | | -------------------------- | -------------------------------- | | {{< icon "thumbs-up" >}} | `{{}}` | | {{< 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. - +### Usage + + ```tpl {{}} {{}} # macOS Content {{}} @@ -270,6 +286,7 @@ Tabs let you organize content by context, for example installation instructions {{}} # Windows Content {{}} {{}} ``` + ### 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. -### 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 @@ -334,6 +343,14 @@ Boxes can be used to create a simple grid. {{}} ``` +#### Attributes + + + +{{< propertylist name=shortcode-boxes sort=name order=asc >}} + + + ### Example @@ -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. - - -### Example +### Usage ```tpl -{{}} +{{}} sequenceDiagram Alice->>Bob: Hello Bob, how are you? alt is sick @@ -371,9 +386,19 @@ sequenceDiagram opt Extra response Bob->>Alice: Thanks for asking end -{{}} +{{}} ``` +#### Attributes + + + +{{< propertylist name=shortcode-mermaid sort=name order=asc >}} + + + +### Example + {{< mermaid class="text-center" >}} @@ -389,6 +414,8 @@ sequenceDiagram end {{< /mermaid >}} + + As an alternative to shortcodes, code blocks can be used for markdown as well. {{< columns >}} @@ -424,14 +451,24 @@ C -->|Two| E[Result 2] [KaTeX](https://katex.org/) shortcode let you render math typesetting in markdown document. -### Example +### Usage ```latex -{{}} +{{}} f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi -{{}} +{{}} ``` +#### Attributes + + + +{{< propertylist name=shortcode-katex sort=name order=asc >}} + + + +### Example + {{< katex display >}} @@ -440,33 +477,65 @@ f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi -KaTeX can be used inline, for example {{< katex >}}\pi(x){{< /katex >}} or used with the `display` parameter (see above). - -Text continues here. +KaTeX can be used inline, for example {{< katex >}}\pi(x){{< /katex >}} or used with the `display` parameter as above. ## Progress -### Attributes +### Usage + + +```tpl +{{}} +``` + +#### Attributes + + + +{{< propertylist name=shortcode-progress sort=name order=asc >}} + + + +### Example + + + +{{< progress title=Eating value=65 icon=gblog_heart >}} + + + +## Properties -| 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 | +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 ```tpl -{{}} +{{}} ``` +The supported attributes can be taken from the following example: + + + +{{< include file="/data/properties/demo.yaml" language="Yaml" options="linenos=table" >}} + + + +#### Attributes + + + +{{< propertylist name=shortcode-buttons sort=name order=asc >}} + + + ### Example -{{< progress title=Eating value=65 icon=gblog_heart >}} +{{< propertylist name=demo sort=name order=asc >}} diff --git a/exampleSite/data/properties/shortcode-boxes.yaml b/exampleSite/data/properties/shortcode-boxes.yaml new file mode 100644 index 0000000..84f90bd --- /dev/null +++ b/exampleSite/data/properties/shortcode-boxes.yaml @@ -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 diff --git a/exampleSite/data/properties/shortcode-buttons.yaml b/exampleSite/data/properties/shortcode-buttons.yaml new file mode 100644 index 0000000..71275c6 --- /dev/null +++ b/exampleSite/data/properties/shortcode-buttons.yaml @@ -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 diff --git a/exampleSite/data/properties/shortcode-columns.yaml b/exampleSite/data/properties/shortcode-columns.yaml new file mode 100644 index 0000000..77104b9 --- /dev/null +++ b/exampleSite/data/properties/shortcode-columns.yaml @@ -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 diff --git a/exampleSite/data/properties/shortcode-hints.yaml b/exampleSite/data/properties/shortcode-hints.yaml new file mode 100644 index 0000000..df472b4 --- /dev/null +++ b/exampleSite/data/properties/shortcode-hints.yaml @@ -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 diff --git a/exampleSite/data/properties/shortcode-katex.yaml b/exampleSite/data/properties/shortcode-katex.yaml new file mode 100644 index 0000000..2dc0d89 --- /dev/null +++ b/exampleSite/data/properties/shortcode-katex.yaml @@ -0,0 +1,6 @@ +--- +properties: + - name: class + type: list + description: List of space-separated CSS class names to apply. + required: false diff --git a/exampleSite/data/properties/shortcode-mermaid.yaml b/exampleSite/data/properties/shortcode-mermaid.yaml new file mode 100644 index 0000000..2dc0d89 --- /dev/null +++ b/exampleSite/data/properties/shortcode-mermaid.yaml @@ -0,0 +1,6 @@ +--- +properties: + - name: class + type: list + description: List of space-separated CSS class names to apply. + required: false diff --git a/exampleSite/data/properties/shortcode-progress.yaml b/exampleSite/data/properties/shortcode-progress.yaml new file mode 100644 index 0000000..39d3cd0 --- /dev/null +++ b/exampleSite/data/properties/shortcode-progress.yaml @@ -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