From 2033d50005ae489e0e31705e3a814c470f7497a3 Mon Sep 17 00:00:00 2001 From: Ludovic Fernandez Date: Fri, 15 Aug 2025 03:09:58 +0200 Subject: [PATCH] docs: add documentation on all shortcodes (#753) --- layouts/_shortcodes/badge.html | 16 ++++++++++++++++ layouts/_shortcodes/callout.html | 11 +++++++++++ layouts/_shortcodes/card.html | 17 +++++++++++++++++ layouts/_shortcodes/cards.html | 8 ++++++++ layouts/_shortcodes/details.html | 9 +++++++++ layouts/_shortcodes/filetree/container.html | 6 ++++++ layouts/_shortcodes/filetree/file.html | 9 ++++++++- layouts/_shortcodes/filetree/folder.html | 9 +++++++++ layouts/_shortcodes/hextra/feature-card.html | 15 +++++++++++++++ layouts/_shortcodes/hextra/feature-grid.html | 9 +++++++++ layouts/_shortcodes/hextra/hero-badge.html | 11 ++++++++++- layouts/_shortcodes/hextra/hero-button.html | 10 ++++++++++ layouts/_shortcodes/hextra/hero-container.html | 18 ++++++++++++++++++ layouts/_shortcodes/hextra/hero-headline.html | 9 ++++++++- layouts/_shortcodes/hextra/hero-section.html | 10 ++++++++++ layouts/_shortcodes/hextra/hero-subtitle.html | 9 ++++++++- layouts/_shortcodes/icon.html | 14 ++++++++++++++ layouts/_shortcodes/jupyter.html | 9 ++++++++- layouts/_shortcodes/pdf.html | 8 +++++++- layouts/_shortcodes/steps.html | 6 ++++++ layouts/_shortcodes/tab.html | 6 ++++++ layouts/_shortcodes/tabs.html | 9 +++++++++ 22 files changed, 222 insertions(+), 6 deletions(-) diff --git a/layouts/_shortcodes/badge.html b/layouts/_shortcodes/badge.html index 370083a..8ff2836 100644 --- a/layouts/_shortcodes/badge.html +++ b/layouts/_shortcodes/badge.html @@ -1,3 +1,19 @@ +{{- /* +A shortcode to create a badge. + +@param {string} content The content of the badge. +@param {string} type The type of the badge. +@param {string} class The class of the badge. +@param {string} link The link of the badge. +@param {string} icon The icon of the badge. + +or + +@param {string} 0 The content of the badge. + +@example {{< badge content="info" type="info" >}} +*/ -}} + {{- if .IsNamedParams -}} {{- $content := .Get "content" -}} {{- $type := .Get "type" | default "" -}} diff --git a/layouts/_shortcodes/callout.html b/layouts/_shortcodes/callout.html index 8b5b8d5..5ccac93 100644 --- a/layouts/_shortcodes/callout.html +++ b/layouts/_shortcodes/callout.html @@ -1,3 +1,14 @@ +{{- /* +A shortcode to create a callout. + +@param {string} type The type of the callout (default, info, warning, error). +@param {string} content The content of the callout. +@param {string} emoji The emoji of the callout (related to type or can be a custom emoji). +@param {string} icon The icon of the callout. + +@example {{< callout type="info" >}}Content{{< /callout >}} +*/ -}} + {{- $calloutEmojiDict := dict "info" "ℹ️" "warning" "⚠️" "error" "🚫" -}} {{- $type := .Get "type" | default "default" -}} {{/* If emoji is not set, use the emoji from dict */}} diff --git a/layouts/_shortcodes/card.html b/layouts/_shortcodes/card.html index 1301bba..b623fc3 100644 --- a/layouts/_shortcodes/card.html +++ b/layouts/_shortcodes/card.html @@ -1,3 +1,20 @@ +{{- /* +A shortcode to create a card. + +@param {string} link The link to the card. +@param {string} title The title of the card. +@param {string} icon The icon of the card. +@param {string} subtitle The subtitle of the card. +@param {string} tag The tag of the card. +@param {string} tagType The type of the tag. +@param {string} image The image of the card. +@param {string} method The method to process the image. +@param {string} options The options to process the image. +@param {string} imageStyle The style of the image. + +@example {{< card link="/" title="Image Card" }} +*/ -}} + {{- $context := . -}} {{- $link := .Get "link" -}} {{- $title := .Get "title" -}} diff --git a/layouts/_shortcodes/cards.html b/layouts/_shortcodes/cards.html index 9230128..0b6667f 100644 --- a/layouts/_shortcodes/cards.html +++ b/layouts/_shortcodes/cards.html @@ -1,3 +1,11 @@ +{{- /* +A shortcode for creating cards. + +@param {string} cols The number of columns. + +@example {{< cards cols="3" >}}{{< /cards >}} +*/ -}} + {{- $cols := .Get "cols" | default 3 -}} {{- partial "shortcodes/cards" (dict "cols" $cols "content" .Inner) -}} diff --git a/layouts/_shortcodes/details.html b/layouts/_shortcodes/details.html index f27e1e9..66775ad 100644 --- a/layouts/_shortcodes/details.html +++ b/layouts/_shortcodes/details.html @@ -1,3 +1,12 @@ +{{- /* +A built-in component to display a collapsible content. + +@param {string} title The title of the details. +@param {string} closed Whether the details are closed or not (default: false). + +@example {{% details title="Details" %}}Content{{% /details %}} +*/ -}} + {{- $title := .Get "title" | default "" -}} {{- $closed := eq (.Get "closed") "true" | default false -}} diff --git a/layouts/_shortcodes/filetree/container.html b/layouts/_shortcodes/filetree/container.html index a679ad4..4efa192 100644 --- a/layouts/_shortcodes/filetree/container.html +++ b/layouts/_shortcodes/filetree/container.html @@ -1,3 +1,9 @@ +{{- /* +A file tree container. + +@example {{< filetree/container >}}{{< /filetree/container >}} +*/ -}} +
{{- .InnerDeindent -}} diff --git a/layouts/_shortcodes/filetree/file.html b/layouts/_shortcodes/filetree/file.html index 3e08248..c48c8c9 100644 --- a/layouts/_shortcodes/filetree/file.html +++ b/layouts/_shortcodes/filetree/file.html @@ -1,5 +1,12 @@ -{{- $name := .Get "name" -}} +{{- /* +A file in a file tree. +@param {string} name The name of the file. + +@example {{< filetree/file name="_index.md" >}} +*/ -}} + +{{- $name := .Get "name" -}}
  • diff --git a/layouts/_shortcodes/filetree/folder.html b/layouts/_shortcodes/filetree/folder.html index 47b8045..c8139e8 100644 --- a/layouts/_shortcodes/filetree/folder.html +++ b/layouts/_shortcodes/filetree/folder.html @@ -1,3 +1,12 @@ +{{- /* +A folder in a file tree. + +@param {string} name The name of the folder. +@param {string} state The state of the folder. + +@example {{< filetree/folder name="docs" state="closed" >}} +*/ -}} + {{- $name := .Get "name" -}} {{- $state := .Get "state" | default "open" }} diff --git a/layouts/_shortcodes/hextra/feature-card.html b/layouts/_shortcodes/hextra/feature-card.html index 39204d6..fd8a648 100644 --- a/layouts/_shortcodes/hextra/feature-card.html +++ b/layouts/_shortcodes/hextra/feature-card.html @@ -1,3 +1,18 @@ +{{- /* +A shortcode for displaying a feature card. + +@param {string} title The title of the card. +@param {string} subtitle The subtitle of the card. +@param {string} class The class of the card. +@param {string} image The image of the card. +@param {string} imageClass The class of the image. +@param {string} style The style of the card. +@param {string} icon The icon of the card. +@param {string} link The link of the card. + +@example {{< hextra/feature-card title="Feature Card" subtitle="This is a feature card." >}} +*/ -}} + {{- $title := .Get "title" -}} {{- $subtitle := .Get "subtitle" -}} {{- $class := .Get "class" -}} diff --git a/layouts/_shortcodes/hextra/feature-grid.html b/layouts/_shortcodes/hextra/feature-grid.html index e217bc8..aace898 100644 --- a/layouts/_shortcodes/hextra/feature-grid.html +++ b/layouts/_shortcodes/hextra/feature-grid.html @@ -1,3 +1,12 @@ +{{- /* +A shortcode for displaying a feature grid. + +@param {string} cols The number of columns. +@param {string} style The style of the grid. + +@example {{< hextra/feature-grid cols="3" >}}{{< /hextra/feature-grid >}} +*/ -}} + {{- $cols := .Get "cols" | default 3 -}} {{- $style := .Get "style" | default "" -}} diff --git a/layouts/_shortcodes/hextra/hero-badge.html b/layouts/_shortcodes/hextra/hero-badge.html index 83895b8..9fdcbbd 100644 --- a/layouts/_shortcodes/hextra/hero-badge.html +++ b/layouts/_shortcodes/hextra/hero-badge.html @@ -1,10 +1,19 @@ +{{- /* +A shortcode for rendering a badge with a link. + +@param {string} link The link of the badge. +@param {string} class The class of the badge. +@param {string} style The style of the badge. + +@example {{< hextra/hero-badge >}}{{< /hextra/hero-badge >}} +*/ -}} + {{- $link := .Get "link" -}} {{- $external := hasPrefix $link "http" -}} {{- $href := cond (hasPrefix $link "/") ($link | relURL) $link -}} {{- $class := .Get "class" }} {{- $style := .Get "style" -}} - }} +*/ -}} + {{- $link := .Get "link" -}} {{- $text := .Get "text" -}} {{- $style := .Get "style" -}} diff --git a/layouts/_shortcodes/hextra/hero-container.html b/layouts/_shortcodes/hextra/hero-container.html index 7da6fed..a7153d4 100644 --- a/layouts/_shortcodes/hextra/hero-container.html +++ b/layouts/_shortcodes/hextra/hero-container.html @@ -1,3 +1,21 @@ +{{- /* +A simple hero container with an image on the left side. + +@param {string} class The class of the container. +@param {string} cols The number of columns (default: 2). +@param {string} image The image of the container. +@param {bool} imageCard Whether to display the image as a card (default: false). +@param {string} imageClass The class of the image. +@param {string} imageLink The link of the image. +@param {string} imageStyle The style of the image. +@param {string} imageTitle The title of the image. +@param {int} imageWidth The width of the image (default: 350). +@param {int} imageHeight The height of the image (default: 350). +@param {string} style The style of the container. + +@example {{< hextra/hero-container image="image.png" imageLink="https://example.com" imageTitle="Example Image" >}} +*/ -}} + {{- $class := .Get "class" -}} {{- $cols := .Get "cols" | default 2 -}} {{- $image := .Get "image" -}} diff --git a/layouts/_shortcodes/hextra/hero-headline.html b/layouts/_shortcodes/hextra/hero-headline.html index 5260cb6..6dd313a 100644 --- a/layouts/_shortcodes/hextra/hero-headline.html +++ b/layouts/_shortcodes/hextra/hero-headline.html @@ -1,5 +1,12 @@ -{{- $style := .Get "style" -}} +{{- /* +A shortcode for displaying a hero headline. +@param {string} style The style of the headline. + +@example {{< hextra/hero-headline >}}{{< /hextra/hero-headline >}} +*/ -}} + +{{- $style := .Get "style" -}}

    }}{{< /hextra/hero-section >}}> +*/ -}} + {{- $style := .Get "style" -}} {{- $heading := int (strings.TrimPrefix "h" (.Get "heading" | default "h2")) -}} {{- $size := cond (ge $heading 4) "xl" (cond (eq $heading 3) "2xl" "4xl") -}} diff --git a/layouts/_shortcodes/hextra/hero-subtitle.html b/layouts/_shortcodes/hextra/hero-subtitle.html index bdaa829..614c427 100644 --- a/layouts/_shortcodes/hextra/hero-subtitle.html +++ b/layouts/_shortcodes/hextra/hero-subtitle.html @@ -1,5 +1,12 @@ -{{- $style := .Get "style" -}} +{{- /* +A shortcode for displaying a hero subtitle. +@param {string} style The style of the subtitle. + +@example {{< hextra/hero-subtitle >}}{{< /hextra/hero-subtitle >}} +*/ -}} + +{{- $style := .Get "style" -}}

    }} +@example {{< icon "github" >}} +*/ -}} + {{- $name := .Get "name" | default (.Get 0) -}} {{- $icon := index site.Data.icons $name -}} {{- $attributes := .Get "attributes" | default "height=1em"}} diff --git a/layouts/_shortcodes/jupyter.html b/layouts/_shortcodes/jupyter.html index e2ff643..ee8e16c 100644 --- a/layouts/_shortcodes/jupyter.html +++ b/layouts/_shortcodes/jupyter.html @@ -1,4 +1,11 @@ -{{/* Render Jupyter Notebook */}} +{{- /* +Render Jupyter Notebook + +@param {string} 0 The path of the Jupyter Notebook. + +@example {{% jupyter "notebook.ipynb" %}} +*/ -}} + {{- $path := .Get 0 -}} {{- $data := "" -}} {{- $page := .Page -}} diff --git a/layouts/_shortcodes/pdf.html b/layouts/_shortcodes/pdf.html index 9e3c4a9..40d4cf5 100644 --- a/layouts/_shortcodes/pdf.html +++ b/layouts/_shortcodes/pdf.html @@ -1,4 +1,10 @@ -{{/* Shortcode to include a PDF file in a page. */}} +{{- /* +Shortcode to include a PDF file in a page. + +@param {string} 0 The path to the PDF file. + +@example {{< pdf "path/to/file.pdf" >}} +*/ -}} {{- $path := .Get 0 -}} {{- $url := partial "utils/file-path" (dict "page" .Page "path" $path) -}} diff --git a/layouts/_shortcodes/steps.html b/layouts/_shortcodes/steps.html index bfe792e..1bccad1 100644 --- a/layouts/_shortcodes/steps.html +++ b/layouts/_shortcodes/steps.html @@ -1,3 +1,9 @@ +{{- /* +A shortcode for creating a step list. + +@example {{% steps %}}{{% /steps %}} +*/ -}} +

    {{- .Inner -}}
    diff --git a/layouts/_shortcodes/tab.html b/layouts/_shortcodes/tab.html index e5a406a..f2f4233 100644 --- a/layouts/_shortcodes/tab.html +++ b/layouts/_shortcodes/tab.html @@ -1,3 +1,9 @@ +{{- /* +Create a tab. + +@example {{< tab >}}content{{< /tab >}} +*/ -}} + {{- $defaultIndex := int ((.Parent.Get "defaultIndex") | default "0") -}}
    }}{{< /tabs >}} +*/ -}} + {{- $items := split (.Get "items") "," -}} {{- $defaultIndex := int ((.Get "defaultIndex") | default "0") -}}