docs: add documentation on all shortcodes (#753)

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 "" -}}

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 */}}

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" -}}

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) -}}

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

layouts/_shortcodes/filetree/container.html

@@ -1,3 +1,9 @@
+{{- /*
+A file tree container.
+
+@example {{< filetree/container >}}{{< /filetree/container >}}
+*/ -}}
+
 <div class="hextra-filetree hx:mt-6 hx:select-none hx:text-sm hx:text-gray-800 hx:dark:text-gray-300 not-prose">
   <div class="hx:inline-block hx:rounded-lg hx:px-4 hx:py-2 hx:border hx:border-gray-200 hx:dark:border-neutral-800">
     {{- .InnerDeindent -}}

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" -}}
 
 <li class="hx:flex hx:list-none">
   <span class="hx:inline-flex hx:cursor-default hx:items-center hx:py-1">

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" }}
 

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" -}}

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 "" -}}
 

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" -}}
 
-
 <a
   {{ if $link }}href="{{ $href }}"{{ end }}
   class="{{ $class }} not-prose hx:inline-flex hx:items-center hx:rounded-full hx:gap-2 hx:px-3 hx:py-1 hx:text-xs hx:text-gray-600 hx:dark:text-gray-400 hx:bg-gray-100 hx:dark:bg-neutral-800 hx:border-gray-200 hx:dark:border-neutral-800 hx:border hx:hover:border-gray-400 hx:dark:hover:text-gray-50 hx:dark:hover:border-gray-600 hx:transition-all hx:ease-in hx:duration-200"

layouts/_shortcodes/hextra/hero-button.html

@@ -1,3 +1,13 @@
+{{- /*
+A shortcode for rendering a button with a link.
+
+@param {string} link The link of the button.
+@param {string} text The text of the button.
+@param {string} style The style of the button.
+
+@example {{< hextra/hero-button text="Get Started" link="docs" >}}
+*/ -}}
+
 {{- $link := .Get "link" -}}
 {{- $text := .Get "text" -}}
 {{- $style := .Get "style" -}}

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" -}}

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" -}}
 
 <h1
   class="not-prose hx:text-4xl hx:font-bold hx:leading-none hx:tracking-tighter hx:md:text-5xl hx:py-2 hx:bg-clip-text hx:text-transparent hx:bg-gradient-to-r hx:from-gray-900 hx:to-gray-600 hx:dark:from-gray-100 hx:dark:to-gray-400"

layouts/_shortcodes/hextra/hero-section.html

@@ -1,3 +1,13 @@
+{{- /*
+A simple hero section with a heading and optional style.
+
+@param {string} heading The heading level (default: h2).
+@param {string} style The style of the heading.
+@param {string} content The content of the heading.
+
+@example {{< hextra/hero-section heading="h3" >}}{{< /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") -}}

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" -}}
 
 <p
   class="not-prose hx:text-xl hx:text-gray-600 hx:dark:text-gray-400 hx:sm:text-xl"

layouts/_shortcodes/icon.html

@@ -1,3 +1,17 @@
+{{- /*
+Create an icon.
+
+@param {string} name The name of the icon.
+@param {string} attributes The attributes of the icon.
+
+or
+
+@param {string} 0 The name of the icon.
+
+@example {{< icon name="github" >}}
+@example {{< icon "github" >}}
+*/ -}}
+
 {{- $name := .Get "name" | default (.Get 0) -}}
 {{- $icon := index site.Data.icons $name -}}
 {{- $attributes := .Get "attributes" | default "height=1em"}}

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

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) -}}

layouts/_shortcodes/steps.html

@@ -1,3 +1,9 @@
+{{- /*
+A shortcode for creating a step list.
+
+@example {{% steps %}}{{% /steps %}}
+*/ -}}
+
 <div class="hextra-steps hx:ml-4 hx:mb-12 hx:ltr:border-l hx:rtl:border-r hx:border-gray-200 hx:ltr:pl-6 hx:rtl:pr-6 hx:dark:border-neutral-800 [counter-reset:step]">
   {{- .Inner -}}
 </div>

layouts/_shortcodes/tab.html

@@ -1,3 +1,9 @@
+{{- /*
+Create a tab.
+
+@example {{< tab >}}content{{< /tab >}}
+*/ -}}
+
 {{- $defaultIndex := int ((.Parent.Get "defaultIndex") | default "0") -}}
 
 <div

layouts/_shortcodes/tabs.html

@@ -1,3 +1,12 @@
+{{- /*
+Create a tabbed interface with the given items.
+
+@param {string} items The items to display in the tabs.
+@param {string} defaultIndex The index of the default tab.
+
+@example {{< tabs items="JSON,YAML,TOML" >}}{{< /tabs >}}
+*/ -}}
+
 {{- $items := split (.Get "items") "," -}}
 {{- $defaultIndex := int ((.Get "defaultIndex") | default "0") -}}