From 51cb8663bade17c392fcf0f8ef0c674723563535 Mon Sep 17 00:00:00 2001
From: Federico Agostini <43784886+Agos95@users.noreply.github.com>
Date: Sun, 28 Aug 2022 00:25:35 +0200
Subject: [PATCH] docs: add comments to document shortcode params (#2796)

---
 .../wowchemy/layouts/shortcodes/audio.html    | 12 ++++++
 .../wowchemy/layouts/shortcodes/callout.html  | 11 ++++++
 .../wowchemy/layouts/shortcodes/chart.html    | 12 +++++-
 modules/wowchemy/layouts/shortcodes/cite.html | 11 ++++++
 modules/wowchemy/layouts/shortcodes/cta.html  | 19 +++++++++
 .../layouts/shortcodes/emoji_list.html        |  4 ++
 .../wowchemy/layouts/shortcodes/figure.html   | 39 ++++++++++++++++++-
 .../wowchemy/layouts/shortcodes/gallery.html  | 15 ++++++-
 .../wowchemy/layouts/shortcodes/gdocs.html    |  9 +++++
 modules/wowchemy/layouts/shortcodes/hl.html   |  4 ++
 modules/wowchemy/layouts/shortcodes/icon.html | 15 +++++++
 .../layouts/shortcodes/list_categories.html   |  4 ++
 .../layouts/shortcodes/list_children.html     |  9 +++++
 .../layouts/shortcodes/list_tags.html         |  4 ++
 modules/wowchemy/layouts/shortcodes/math.html |  4 ++
 .../wowchemy/layouts/shortcodes/mention.html  |  9 +++++
 .../wowchemy/layouts/shortcodes/spoiler.html  | 13 +++++++
 .../layouts/shortcodes/staticref.html         | 12 +++++-
 .../wowchemy/layouts/shortcodes/table.html    | 15 +++++++
 modules/wowchemy/layouts/shortcodes/toc.html  | 13 +++++++
 .../wowchemy/layouts/shortcodes/video.html    | 20 +++++++++-
 21 files changed, 249 insertions(+), 5 deletions(-)

diff --git a/modules/wowchemy/layouts/shortcodes/audio.html b/modules/wowchemy/layouts/shortcodes/audio.html
index 3ef93b66..85f4dda0 100644
--- a/modules/wowchemy/layouts/shortcodes/audio.html
+++ b/modules/wowchemy/layouts/shortcodes/audio.html
@@ -2,6 +2,18 @@
 {{/* Load audio from page dir falling back to media library at `assets/media/` and then to remote URI. */}}
 {{/* Supports primarily MP3 and MP4. */}}
 
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#audio
+
+    Parameters
+    ----------
+    src :
+        Path to file or url for the audio file.
+        If a local file, first it is searched in the page directory, and then in `assets/media/` .
+    id : optional
+        Custom id "audio-{id}" to associate to the <audio> tag.
+*/}}
+
 {{ $destination := .Get "src" }}
 {{ $is_remote := strings.HasPrefix $destination "http" }}
 {{- $asset := "" -}}
diff --git a/modules/wowchemy/layouts/shortcodes/callout.html b/modules/wowchemy/layouts/shortcodes/callout.html
index e1a41b27..a4285a0a 100644
--- a/modules/wowchemy/layouts/shortcodes/callout.html
+++ b/modules/wowchemy/layouts/shortcodes/callout.html
@@ -1,3 +1,14 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#callouts
+
+    Parameters
+    ----------
+    #0 : optional, positional
+        Add the class "alert-{#0}" to the <div> container of the callout element.
+        Default Wowchemy available styles are "note" and "warning".
+        Otherwise you can create your own class (see `assets/scss/wowchemy/elements/_callout.scss`).
+*/}}
+
 <div class="alert alert-{{ .Get 0 }}">
   <div>
     {{ .Inner | markdownify | emojify  }}
diff --git a/modules/wowchemy/layouts/shortcodes/chart.html b/modules/wowchemy/layouts/shortcodes/chart.html
index fedd02a2..7aa467c5 100644
--- a/modules/wowchemy/layouts/shortcodes/chart.html
+++ b/modules/wowchemy/layouts/shortcodes/chart.html
@@ -1,3 +1,13 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#charts
+
+    Parameters
+    ----------
+    data :
+        Plotly JSON file name (without ".json" extension, since it is appended automatically to the name).
+        Expects the JSON file to be placed in the page folder.
+*/}}
+
 {{ $json := printf "./%s.json" (.Get "data") }}
 {{ $id := delimit (shuffle (seq 1 9)) "" }}
 <div id="chart-{{$id}}" class="chart"></div>
@@ -14,4 +24,4 @@
       });
     }, 500 );
   })();
-</script>
\ No newline at end of file
+</script>
diff --git a/modules/wowchemy/layouts/shortcodes/cite.html b/modules/wowchemy/layouts/shortcodes/cite.html
index 4fb8c552..6036b12e 100644
--- a/modules/wowchemy/layouts/shortcodes/cite.html
+++ b/modules/wowchemy/layouts/shortcodes/cite.html
@@ -1,3 +1,14 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#cite
+
+    Parameters
+    ----------
+    page : required
+        Path to Markdown page to be referenced.
+    view : optional, default "compact"
+        A built-in Wowchemy view or an installed community view.
+*/}}
+
 {{ $page := .Page }}
 {{ $item := .Get "page" }}
 
diff --git a/modules/wowchemy/layouts/shortcodes/cta.html b/modules/wowchemy/layouts/shortcodes/cta.html
index 17770c81..99646078 100644
--- a/modules/wowchemy/layouts/shortcodes/cta.html
+++ b/modules/wowchemy/layouts/shortcodes/cta.html
@@ -1,3 +1,22 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#call-to-action-buttons
+
+    Parameters
+    ----------
+    cta_text :
+        Text to display in the CTA button.
+    cta_link :
+        Link to action when CTA button is clicked.
+    cta_new_tab : default "false"
+        If "true", open the link in a new tab.
+    cta_alt_text : optional
+        Alternate text to display in the CTA button.
+    cta_alt_link : optional
+       Link to alternative action when CTA button is clicked.
+    cta_alt_new_tab : optional, default "false"
+        If "true", open the alternative link in a new tab.
+*/}}
+
 <ul class="cta-group">
   {{ if (.Get "cta_text") }}
   <li>
diff --git a/modules/wowchemy/layouts/shortcodes/emoji_list.html b/modules/wowchemy/layouts/shortcodes/emoji_list.html
index b4223ca6..06948af3 100644
--- a/modules/wowchemy/layouts/shortcodes/emoji_list.html
+++ b/modules/wowchemy/layouts/shortcodes/emoji_list.html
@@ -1 +1,5 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#emojis
+*/}}
+
 <div class="emoji-list">{{ .Inner }}</div>
\ No newline at end of file
diff --git a/modules/wowchemy/layouts/shortcodes/figure.html b/modules/wowchemy/layouts/shortcodes/figure.html
index 8327f1cf..aa633ca0 100644
--- a/modules/wowchemy/layouts/shortcodes/figure.html
+++ b/modules/wowchemy/layouts/shortcodes/figure.html
@@ -3,6 +3,43 @@
 {{/* Note: Uses `{{-` to unindent HTML so that Figure shortcode can be nested within a `{{%` Markdown shortcode,
      such as Callout, without the HTML being rendered as a Markdown code block. */}}
 
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#single-image
+
+    Parameters
+    ----------
+    src :
+        Path to file or url for the image.
+        If a local file, first it is searched in the page directory, and then in `assets/media/` .
+    caption : optional
+        Caption to add to the figure.
+    title : optional
+        DEPRECATED. Legacy alias for 'caption'.
+    lightbox : default "true"
+        If 'lightbox' is "true" and no 'link' is specified, the figure is made zoomable.
+    link : optional
+        Link to open on click instead of zooming on click.
+    id : optional
+        Custom id "figure-{id}" to associate to the <figure> tag.
+        The id defaults to the caption if unset.
+    alt : optional
+        Screen reader text. Defaults to the caption if unset.
+    theme : optional
+        One of ["light", "dark"]. Respectively adds the class ["img-light", "img-dark"] to <figure>.
+        If "light", image is inverted when browsing in dark mode; the opposite otherwise.
+    class : optional
+        Optional additional class for <figure>.
+    max_width : optional
+        `max-width` style attribute for the <div class="w-100"> tage inside <figure>.
+        For example, "fit-content" makes the <div> of the same width of the contained image.
+    width : optional
+        `width` attribute of <img>. It defaults to image width.
+    height : optional
+        `height` attribute of <img>. It defaults to image height.
+    numbered : default "false"
+        If "true", the caption is numbered.
+*/}}
+
 {{ $destination := .Get "src" }}
 {{ $is_remote := strings.HasPrefix $destination "http" }}
 {{ $caption := .Get "caption" | default (.Get "title") | default "" }}{{/* Support legacy `title` option. */}}
@@ -76,4 +113,4 @@
       {{ $caption | markdownify | emojify }}
     </figcaption>
   {{- end -}}
-</figure>
\ No newline at end of file
+</figure>
diff --git a/modules/wowchemy/layouts/shortcodes/gallery.html b/modules/wowchemy/layouts/shortcodes/gallery.html
index 29b4a9ff..b1a55f13 100644
--- a/modules/wowchemy/layouts/shortcodes/gallery.html
+++ b/modules/wowchemy/layouts/shortcodes/gallery.html
@@ -2,6 +2,19 @@
 {{/* Load gallery images from media library. */}}
 {{/* https://github.com/wowchemy/wowchemy-hugo-themes */}}
 
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#image-gallery
+
+    Parameters
+    ----------
+    album : default "gallery"
+        Album folder in `assets/media/albums/` to load images from.
+    order : default "asc"
+        Sort images by title ascending (asc) or descending (desc).
+    resize_options : default "750x750"
+        Resize options passed to Hugo `.Fit` function (https://gohugo.io/content-management/image-processing/).
+*/}}
+
 {{/* Get album folder or default to `media/albums/gallery/`. */}}
 {{ $album := (.Get "album") | default "gallery" }}
 {{ $album_path := path.Join "media" "albums" $album "*" }}
@@ -41,4 +54,4 @@
     {{ errorf "Unable to load gallery `%s` in `%s`." $album_path .Page.File.Filename }}
   {{end}}
 
-</div>
\ No newline at end of file
+</div>
diff --git a/modules/wowchemy/layouts/shortcodes/gdocs.html b/modules/wowchemy/layouts/shortcodes/gdocs.html
index aa3ad33a..0982f4e3 100644
--- a/modules/wowchemy/layouts/shortcodes/gdocs.html
+++ b/modules/wowchemy/layouts/shortcodes/gdocs.html
@@ -1,3 +1,12 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#embed-documents
+
+    Parameters
+    ----------
+    src : str
+        Google Docs URL for embedding.
+*/}}
+
 <div class="responsive-wrap">
   <iframe src="{{ .Get "src" }}" frameborder="0" width="960" height="569" allowfullscreen="true" mozallowfullscreen="true" webkitallowfullscreen="true"></iframe>
 </div>
\ No newline at end of file
diff --git a/modules/wowchemy/layouts/shortcodes/hl.html b/modules/wowchemy/layouts/shortcodes/hl.html
index 6f344014..8733c861 100644
--- a/modules/wowchemy/layouts/shortcodes/hl.html
+++ b/modules/wowchemy/layouts/shortcodes/hl.html
@@ -1 +1,5 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#highlight-quote
+*/}}
+
 <mark>{{ .Inner | markdownify | emojify }}</mark>
\ No newline at end of file
diff --git a/modules/wowchemy/layouts/shortcodes/icon.html b/modules/wowchemy/layouts/shortcodes/icon.html
index 38541aba..d3f2ef42 100644
--- a/modules/wowchemy/layouts/shortcodes/icon.html
+++ b/modules/wowchemy/layouts/shortcodes/icon.html
@@ -1,3 +1,18 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#inline-image
+
+    Parameters
+    ----------
+    name :
+        Icon name.
+    pack : default "fas"
+        Icon pack.
+    padding_left : default "0"
+        Left padding.
+    padding_right : default "1"
+        Right padding.
+*/}}
+
 {{- if (.Get "name") -}}
   {{- $icon := .Get "name" -}}
   {{- $pack := or (.Get "pack") "fas" -}}
diff --git a/modules/wowchemy/layouts/shortcodes/list_categories.html b/modules/wowchemy/layouts/shortcodes/list_categories.html
index 7bbf986a..1a1c1c38 100644
--- a/modules/wowchemy/layouts/shortcodes/list_categories.html
+++ b/modules/wowchemy/layouts/shortcodes/list_categories.html
@@ -1,3 +1,7 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#tags-and-categories
+*/}}
+
 <ul class="list-unstyled">
   {{ range site.Taxonomies.categories }}
   <li><a href="{{.Page.RelPermalink}}">{{.Page.Title}}</a></li>
diff --git a/modules/wowchemy/layouts/shortcodes/list_children.html b/modules/wowchemy/layouts/shortcodes/list_children.html
index e6cfc932..5a7d17bd 100644
--- a/modules/wowchemy/layouts/shortcodes/list_children.html
+++ b/modules/wowchemy/layouts/shortcodes/list_children.html
@@ -1,3 +1,12 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#list-child-pages
+
+    Parameters
+    ----------
+    show_summary : bool, default "false"
+        If "true", show also the summary in addition to the title.
+*/}}
+
 {{ $show_summary := ne (.Get "show_summary") "false" }}
 {{ if gt (len $.Page.Pages) 0}}
   <ul class="list-unstyled">
diff --git a/modules/wowchemy/layouts/shortcodes/list_tags.html b/modules/wowchemy/layouts/shortcodes/list_tags.html
index 43848128..86ffcbaa 100644
--- a/modules/wowchemy/layouts/shortcodes/list_tags.html
+++ b/modules/wowchemy/layouts/shortcodes/list_tags.html
@@ -1,3 +1,7 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#tags-and-categories
+*/}}
+
 <ul class="list-unstyled">
   {{ range site.Taxonomies.tags }}
   <li><a href="{{.Page.RelPermalink}}">{{.Page.Title}}</a></li>
diff --git a/modules/wowchemy/layouts/shortcodes/math.html b/modules/wowchemy/layouts/shortcodes/math.html
index 88c822a3..dee7953d 100644
--- a/modules/wowchemy/layouts/shortcodes/math.html
+++ b/modules/wowchemy/layouts/shortcodes/math.html
@@ -1 +1,5 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#math
+*/}}
+
 {{ .Inner }}
\ No newline at end of file
diff --git a/modules/wowchemy/layouts/shortcodes/mention.html b/modules/wowchemy/layouts/shortcodes/mention.html
index 7347faa7..f97374df 100644
--- a/modules/wowchemy/layouts/shortcodes/mention.html
+++ b/modules/wowchemy/layouts/shortcodes/mention.html
@@ -1,3 +1,12 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#mention-a-user
+
+    Parameters
+    ----------
+    #0 : positional
+        User account in Wowchemy to mention.
+*/}}
+
 {{- $username := .Get 0 -}}
 {{- $username_url := $username | urlize -}}
 {{- $taxonomy := "authors" -}}
diff --git a/modules/wowchemy/layouts/shortcodes/spoiler.html b/modules/wowchemy/layouts/shortcodes/spoiler.html
index 6559cbb0..0cb6eca5 100644
--- a/modules/wowchemy/layouts/shortcodes/spoiler.html
+++ b/modules/wowchemy/layouts/shortcodes/spoiler.html
@@ -1,3 +1,16 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#toggle-list
+
+    Parameters
+    ----------
+    text :
+        Spoiler title.
+    class : optional
+        Additional class for <details> tag.
+    style : optional
+        Additional style for <details> tag.
+*/}}
+
 {{- $id := printf "spoiler-%d" .Ordinal -}}
 
 <details class="spoiler {{ .Get "class" }}" {{ with .Get "style" }}style="{{ . | safeCSS }}"{{ end }} id="{{$id}}">
diff --git a/modules/wowchemy/layouts/shortcodes/staticref.html b/modules/wowchemy/layouts/shortcodes/staticref.html
index c6e99f45..8c744948 100644
--- a/modules/wowchemy/layouts/shortcodes/staticref.html
+++ b/modules/wowchemy/layouts/shortcodes/staticref.html
@@ -1 +1,11 @@
-<a href="{{ .Get 0 | relURL }}"{{ if len .Params | eq 2 }} target="_blank"{{ end }}>{{ .Inner }}</a>
\ No newline at end of file
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#link-to-a-page
+    Parameters
+    ----------
+    #0 : positional
+        URL for the link (if local path, it is relative to the page folder).
+    #1 : optional, positional
+        Pass "newtab" as the second argument to open the link in a new tab.
+*/}}
+
+<a href="{{ .Get 0 | relURL }}"{{ if len .Params | eq 2 }} target="_blank"{{ end }}>{{ .Inner }}</a>
diff --git a/modules/wowchemy/layouts/shortcodes/table.html b/modules/wowchemy/layouts/shortcodes/table.html
index 69150948..c1dfe3a4 100644
--- a/modules/wowchemy/layouts/shortcodes/table.html
+++ b/modules/wowchemy/layouts/shortcodes/table.html
@@ -2,6 +2,21 @@
 {{/* Load a CSV table from page dir falling back back to remote URL */}}
 {{/* Defaults to expecting a comma-separated CSV with a header row. */}}
 
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#csv-table
+
+    Parameters
+    ----------
+    src :
+        Path or url to the csv table. Path is relative to the folder where the shortcode is called.
+    delimiter : default ","
+        Field delimiter.
+    header : default "true"
+        If "true", the first row is rendered as the header.
+    caption : optional
+        Caption for the table.
+*/}}
+
 {{ $src := .Get "path" }}
 {{ $delimiter := .Get "delimiter" | default "," }}
 {{ $useHeaderRow := (eq (lower (.Get "header")) "true") | default true }}
diff --git a/modules/wowchemy/layouts/shortcodes/toc.html b/modules/wowchemy/layouts/shortcodes/toc.html
index 02d39346..64cdb047 100644
--- a/modules/wowchemy/layouts/shortcodes/toc.html
+++ b/modules/wowchemy/layouts/shortcodes/toc.html
@@ -1,3 +1,16 @@
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#table-of-contents
+
+    Parameters
+    ----------
+    hide_on : optional
+        Hide TOC for a certain screen size.
+        For instance, with `hide_on="xl"`,
+        the in page TOC only appears when the right sidebar of the book layout is hidden.
+    show_on : optional
+        Same as above, but for showing the TOC only on certain screen size.
+*/}}
+
 <details class="toc-inpage d-print-none {{with .Get "hide_on"}}d-{{.}}-none{{end}} {{with .Get "show_on"}}d-none d-{{.}}-block{{end}}" open>
   <summary class="font-weight-bold">{{ i18n "table_of_contents" }}</summary>
   {{ $.Page.TableOfContents }}
diff --git a/modules/wowchemy/layouts/shortcodes/video.html b/modules/wowchemy/layouts/shortcodes/video.html
index 9e361b24..7cafb7a3 100644
--- a/modules/wowchemy/layouts/shortcodes/video.html
+++ b/modules/wowchemy/layouts/shortcodes/video.html
@@ -1,6 +1,24 @@
 {{/* Video Shortcode for Wowchemy. */}}
 {{/* Load video from page dir falling back to media library at `assets/media/` and then to remote URI. */}}
 
+{{/*
+    Docs: https://wowchemy.com/docs/content/writing-markdown-latex/#videos
+
+    Parameters
+    ----------
+    src :
+        Path to file or url for the video file.
+        If a local file, first it is searched in the page directory, and then in `assets/media/` .
+    poster : optional
+        Path or url for the preview image.
+        Defaults to {src without file extension}.jpg .
+        If not found, defaults to "".
+    controls : optional
+        If present, display video controls, otherwise the video is set to autoplay.
+    id : optional
+        Custom id "video-{id}" to associate to the <video> tag.
+*/}}
+
 {{ $destination := .Get "src" }}
 {{ $video_ext_with_dot := path.Ext (.Get "src") }}
 {{ $video_ext := strings.TrimPrefix "." $video_ext_with_dot }}
@@ -32,4 +50,4 @@
 
 <video {{if (.Get "controls")}}controls{{else}}autoplay loop{{end}} {{with $poster}}poster="{{.}}"{{end}} {{ with (.Get "id") }}id="video-{{.|anchorize}}"{{end}}>
   <source src="{{$destination}}" type="video/{{$video_type}}">
-</video>
\ No newline at end of file
+</video>