From a346ca1fdae106eccd4d4691e830df0faf76e565 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Thu, 16 Jan 2025 06:56:34 -0800 Subject: [PATCH] Elevate embedded shortcode documentation to its own section --- config/_default/menus/menus.en.toml | 20 +- content/en/content-management/shortcodes.md | 550 +----------------- .../content-management/syntax-highlighting.md | 2 +- .../functions/_common/highlighting-options.md | 59 ++ content/en/functions/images/QR.md | 2 +- content/en/functions/transform/Highlight.md | 83 +-- content/en/methods/page/Path.md | 4 +- content/en/shortcodes/_index.md | 16 + content/en/shortcodes/comment.md | 38 ++ content/en/shortcodes/details.md | 80 +++ content/en/shortcodes/figure.md | 121 ++++ content/en/shortcodes/gist.md | 41 ++ content/en/shortcodes/highlight.md | 118 ++++ content/en/shortcodes/instagram.md | 56 ++ content/en/shortcodes/param.md | 48 ++ content/en/shortcodes/qr.md | 113 ++++ content/en/shortcodes/ref.md | 48 ++ content/en/shortcodes/relref.md | 48 ++ content/en/shortcodes/vimeo.md | 72 +++ content/en/shortcodes/x.md | 62 ++ content/en/shortcodes/youtube.md | 97 +++ content/en/templates/shortcode.md | 4 +- data/docs.yaml | 6 + data/embedded_template_urls.toml | 4 + layouts/shortcodes/hl.html | 4 + 25 files changed, 1067 insertions(+), 629 deletions(-) create mode 100644 content/en/functions/_common/highlighting-options.md create mode 100644 content/en/shortcodes/_index.md create mode 100755 content/en/shortcodes/comment.md create mode 100755 content/en/shortcodes/details.md create mode 100755 content/en/shortcodes/figure.md create mode 100755 content/en/shortcodes/gist.md create mode 100755 content/en/shortcodes/highlight.md create mode 100755 content/en/shortcodes/instagram.md create mode 100755 content/en/shortcodes/param.md create mode 100755 content/en/shortcodes/qr.md create mode 100755 content/en/shortcodes/ref.md create mode 100755 content/en/shortcodes/relref.md create mode 100755 content/en/shortcodes/vimeo.md create mode 100755 content/en/shortcodes/x.md create mode 100755 content/en/shortcodes/youtube.md create mode 100644 layouts/shortcodes/hl.html diff --git a/config/_default/menus/menus.en.toml b/config/_default/menus/menus.en.toml index 3f4e76879..aac432fab 100644 --- a/config/_default/menus/menus.en.toml +++ b/config/_default/menus/menus.en.toml @@ -55,20 +55,26 @@ identifier = 'render-hooks' pageRef = '/render-hooks/' [[docs]] -name = 'Hugo Modules' +name = 'Shortcodes' weight = 100 +identifier = 'shortcodes' +pageRef = '/shortcodes/' + +[[docs]] +name = 'Hugo Modules' +weight = 110 identifier = 'modules' pageRef = '/hugo-modules/' [[docs]] name = 'Hugo Pipes' -weight = 110 +weight = 120 identifier = 'hugo-pipes' pageRef = '/hugo-pipes/' [[docs]] name = 'CLI' -weight = 120 +weight = 130 post = 'break' identifier = 'commands' pageRef = '/commands/' @@ -77,25 +83,25 @@ pageRef = '/commands/' [[docs]] name = 'Troubleshooting' -weight = 130 +weight = 140 identifier = 'troubleshooting' pageRef = '/troubleshooting/' [[docs]] name = 'Developer tools' -weight = 140 +weight = 150 identifier = 'developer-tools' pageRef = '/tools/' [[docs]] name = 'Hosting and deployment' -weight = 150 +weight = 160 identifier = 'hosting-and-deployment' pageRef = '/hosting-and-deployment/' [[docs]] name = 'Contribute' -weight = 160 +weight = 170 post = 'break' identifier = 'contribute' pageRef = '/contribute/' diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md index a486f0c8f..cd1f2cb43 100644 --- a/content/en/content-management/shortcodes.md +++ b/content/en/content-management/shortcodes.md @@ -72,555 +72,7 @@ You can call shortcodes within other shortcodes by creating your own templates t ## Embedded shortcodes -Use these embedded shortcodes as needed. - -### comment - -{{< new-in "0.137.1" >}} - -{{% note %}} -To override Hugo's embedded `comment` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. - -[source code]: {{% eturl comment %}} -{{% /note %}} - -Use the `comment` shortcode to include comments in your Markdown. Hugo excludes the encapsulated text when rendering your site. - -Example usage: - -```text -{{%/* comment */%}} TODO: rewrite the paragraph below. {{%/* /comment */%}} -``` - -Although you can call this shortcode using the `{{}}` notation, computationally it is more efficient to call it using the `{{%/* */%}}` notation as shown above. - -### details - -{{< new-in 0.140.0 >}} - -{{% note %}} -To override Hugo's embedded `details` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. - -[source code]: {{% eturl details %}} -{{% /note %}} - -Use the `details` shortcode to create a `details` HTML element. For example: - -```text -{{}} -This is a **bold** word. -{{}} -``` - -Hugo renders this to: - -```html -
- See the details -

This is a bold word.

-
-``` - -The `details` shortcode accepts these named arguments: - -summary -: (`string`) The content of the child `summary` element rendered from Markdown to HTML. Default is `Details`. - -open -: (`bool`) Whether to initially display the content of the `details` element. Default is `false`. - -class -: (`string`) The value of the element's `class` attribute. - -name -: (`string`) The value of the element's `name` attribute. - -title -: (`string`) The value of the element's `title` attribute. - -### figure - -{{% note %}} -To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. - -[source code]: {{% eturl figure %}} -{{% /note %}} - -The `figure` shortcode can use the following named arguments: - -src -: URL of the image to be displayed. - -link -: If the image needs to be hyperlinked, URL of the destination. - -target -: Optional `target` attribute for the URL if `link` argument is set. - -rel -: Optional `rel` attribute for the URL if `link` argument is set. - -alt -: Alternate text for the image if the image cannot be displayed. - -title -: Image title. - -caption -: Image caption. Markdown within the value of `caption` will be rendered. - -class -: `class` attribute of the HTML `figure` tag. - -height -: `height` attribute of the image. - -width -: `width` attribute of the image. - -loading -: `loading` attribute of the image. - -attr -: Image attribution text. Markdown within the value of `attr` will be rendered. - -attrlink -: If the attribution text needs to be hyperlinked, URL of the destination. - -Example usage: - -```text -{{}} -``` - -Rendered: - -```html -
- -

An elephant at sunset

-
-``` - -### gist - -{{% note %}} -To override Hugo's embedded `gist` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. - -[source code]: {{% eturl gist %}} -{{% /note %}} - -To display a GitHub [gist] with this URL: - -[gist]: https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists - -```text -https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b -``` - -Include this in your Markdown: - -```text -{{}} -``` - -This will display all files in the gist alphabetically by file name. - -{{< gist jmooring 23932424365401ffa5e9d9810102a477 >}} - -To display a specific file within the gist: - -```text -{{}} -``` - -Rendered: - -{{< gist jmooring 23932424365401ffa5e9d9810102a477 list.html >}} - -### highlight - -{{% note %}} -To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. - -[source code]: {{% eturl highlight %}} -{{% /note %}} - -To display a highlighted code sample: - -```text -{{}} -{{ range .Pages }} -

{{ .LinkTitle }}

-{{ end }} -{{}} -``` - -Rendered: - -{{< highlight go-html-template >}} -{{ range .Pages }} -

{{ .LinkTitle }}

-{{ end }} -{{< /highlight >}} - -To specify one or more [highlighting options], include a quotation-encapsulated, comma-separated list: - -[highlighting options]: /functions/transform/highlight/ - -```text -{{}} -{{ range .Pages }} -

{{ .LinkTitle }}

-{{ end }} -{{}} -``` - -Rendered: - -{{< highlight go-html-template "lineNos=inline, lineNoStart=42" >}} -{{ range .Pages }} -

{{ .LinkTitle }}

-{{ end }} -{{< /highlight >}} - -### instagram - -{{% note %}} -To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. - -[source code]: {{% eturl instagram %}} -{{% /note %}} - -To display an Instagram post with this URL: - -```text -https://www.instagram.com/p/CxOWiQNP2MO/ -``` - -Include this in your Markdown: - -```text -{{}} -``` - -Rendered: - -{{< instagram CxOWiQNP2MO >}} - -### param - -{{% note %}} -To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. - -[source code]: {{% eturl param %}} -{{% /note %}} - -The `param` shortcode renders a parameter from the page's front matter, falling back to a site parameter of the same name. The shortcode throws an error if the parameter does not exist. - -Example usage: - -```text -{{}} -``` - -Access nested values by [chaining] the [identifiers]: - -[chaining]: /getting-started/glossary/#chain -[identifiers]: /getting-started/glossary/#identifier - -```text -{{}} -``` - -### qr - -{{% note %}} -To override Hugo's embedded `qr` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. - -[source code]: {{% eturl qr %}} -{{% /note %}} - -The `qr` shortcode encodes the given text into a [QR code] using the specified options and renders the resulting image. - -[QR code]: https://en.wikipedia.org/wiki/QR_code - -Use the self-closing syntax to pass the text as an argument: - -```text -{{}} -``` - -Or insert the text between the opening and closing tags: - -```text -{{}} -https://gohugo.io -{{}} -``` - -Both of the above produce this image: - -{{< qr text="https://gohugo.io" class="qrcode" />}} - -To create a QR code for a phone number: - -```text -{{}} -``` - -{{< qr text="tel:+12065550101" class="qrcode" />}} - -To create a QR code containing contact information in the [vCard] format: - -[vCard]: https://en.wikipedia.org/wiki/VCard - -```text -{{}} -BEGIN:VCARD -VERSION:2.1 -N;CHARSET=UTF-8:Smith;John;R.;Dr.;PhD -FN;CHARSET=UTF-8:Dr. John R. Smith, PhD. -ORG;CHARSET=UTF-8:ABC Widgets -TITLE;CHARSET=UTF-8:Vice President Engineering -TEL;TYPE=WORK:+12065550101 -EMAIL;TYPE=WORK:jsmith@example.org -END:VCARD -{{}} -``` - -{{< qr level="low" scale=2 alt="QR code of vCard for John Smith" class="qrcode" >}} -BEGIN:VCARD -VERSION:2.1 -N;CHARSET=UTF-8:Smith;John;R.;Dr.;PhD -FN;CHARSET=UTF-8:Dr. John R. Smith, PhD. -ORG;CHARSET=UTF-8:ABC Widgets -TITLE;CHARSET=UTF-8:Vice President Engineering -TEL;TYPE=WORK:+12065550101 -EMAIL;TYPE=WORK:jsmith@example.org -END:VCARD -{{< /qr >}} - -Internally this shortcode calls the `images.QR` function. Please read the [related documentation] for implementation details and guidance. - -[related documentation]: /functions/images/qr/ - -The `qr` shortcode accepts these named arguments: - -text -: (`string`) The text to encode, falling back to the text between the opening and closing shortcode tags. - -level -: (`string`) The error correction level to use when encoding the text, one of `low`, `medium`, `quartile`, or `high`. Default is `medium`. - -scale -: (`int`) The number of image pixels per QR code module. Must be greater than or equal to 2. Default is `4`. - -targetDir -: (`string`) The subdirectory within the [`publishDir`] where Hugo will place the generated image. - -[`publishDir`]: /getting-started/configuration/#publishdir - -alt -: (`string`) The `alt` attribute of the `img` element. - -class -: (`string`) The `class` attribute of the `img` element. - -id -: (`string`) The `id` attribute of the `img` element. - -title -: (`string`) The `title` attribute of the `img` element. - -### ref - -{{% note %}} -To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. - -Always use the `{{%/* */%}}` notation when calling this shortcode. - -[source code]: {{% eturl ref %}} -{{% /note %}} - -The `ref` shortcode returns the permalink of the given page reference. - -Example usage: - -```text -[Post 1]({{%/* ref "/posts/post-1" */%}}) -[Post 1]({{%/* ref "/posts/post-1.md" */%}}) -[Post 1]({{%/* ref "/posts/post-1#foo" */%}}) -[Post 1]({{%/* ref "/posts/post-1.md#foo" */%}}) -``` - -Rendered: - -```html -Post 1 -Post 1 -Post 1 -Post 1 -``` - -### relref - -{{% note %}} -To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. - -Always use the `{{%/* */%}}` notation when calling this shortcode. - -[source code]: {{% eturl relref %}} -{{% /note %}} - -The `relref` shortcode returns the permalink of the given page reference. - -Example usage: - -```text -[Post 1]({{%/* relref "/posts/post-1" */%}}) -[Post 1]({{%/* relref "/posts/post-1.md" */%}}) -[Post 1]({{%/* relref "/posts/post-1#foo" */%}}) -[Post 1]({{%/* relref "/posts/post-1.md#foo" */%}}) -``` - -Rendered: - -```html -Post 1 -Post 1 -Post 1 -Post 1 -``` - -### twitter - -{{% note %}} -To override Hugo's embedded `twitter` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. - -[source code]: {{% eturl twitter %}} -{{% /note %}} - -To display a Twitter post with this URL: - -```txt -https://x.com/SanDiegoZoo/status/1453110110599868418 -``` - -Include this in your Markdown: - -```text -{{}} -``` - -Rendered: - -{{< twitter user="SanDiegoZoo" id="1453110110599868418" >}} - -### vimeo - -{{% note %}} -To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. - -[source code]: {{% eturl vimeo %}} -{{% /note %}} - -To display a Vimeo video with this URL: - -```text -https://vimeo.com/channels/staffpicks/55073825 -``` - -Include this in your Markdown: - -```text -{{}} -``` - -Rendered: - -{{< vimeo 55073825 >}} - -{{% note %}} -If you want to further customize the visual styling, add a `class` argument when calling the shortcode. The new `class` will be added to the `
` that wraps the `