Help:Shortcode Variable Structure

Document the section structure.

Variable Structure
Description
Shortcode
Type	HTML Shortcode
Nested?	false
Shortcode	`variable_structure`
Return Type	HTML
Short Description Document the front matter of the different sections of the homepage.
Development
Maintainer	Michael Sasser

The variable_structure is used in the Section Documentation section. It renders a full description of the front matter of a page. It comes with a heading line, some descriptions, a table of variables and there descriptions, in addition how to use the datetime string (if needed) and some generated example.

Parameters

The post shortcode has the following parameters:

Parameter	Description
`1`	The section name
`2..n`	The variables

Examples

{{< variable_structure "Foo" "title" "description" >}}

Rendered

Every Markdown file contains a header section, called front matter, in the YAML format to configure parts of the page or website. A foo page needs the following variables in the front matter.

Variable	Type	Description
`title`	`str`	The title of the page or ressource
`description`	`str`	The page description, normally for SEO

You will find a complete list and how to use them inside the site in the Hugo docs →

Header Example

Remember, the front matter is a YAML structure embedded into the Markdown file. The --- delimiters signal Hugo that this is a front matter in the YAML format. Here is a generated example, how the front matter might look like:


  ---
  title: "MyTitle"
  description: "A description of the page content"# This is an example for a comment in YAML
  ---

Code

Below you find the implementation of the shortcode.

HTML

Defined in layouts/shortcodes/variable_structure.html.

This code is licensed under the MIT license.

<!--

  Variable Structure Shortcode
  ============================

  Contributors: Michael Sasser
  Maintainer: Michael Sasser
  License: MIT
  Version: 1
  Child Shortcodes: None
  Parent Shortcodes: None

  LAYOUT: /layouts/shortcodes/variable_structure.html
  DOCS:   /content/<language>/wiki/Help:Shortcode_Variable_Structure.md

  Description
  -----------

  Use the variable structure shortcode do document the front matter of the
  different sections of the homepage.

  Changelog
  =========

  Version 1
  ---------

  Initial release

-->

{{ $page := (index .Params 0) }}
{{ $fields := after 1 .Params }}
{{ $dt :=
  false
}}

{{ $image := false }}
{{ $contrib := false }}


Every Markdown file contains a header section, called front matter, in the
<i>YAML</i> format to configure parts of the page or website. A
{{ lower $page }} page needs the following variables in the front matter.

<table class="table">
  <thead>
    <tr>
      <th>Variable</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    {{ range $fields }}
      <tr>
        <td><code>{{ . }}</code></td>
        <td>
          <!-- list of (add the list off variable to the of part too) -->
          {{ if eq . "images" "contributors" }}<code>list</code> of{{ end }}
          <!-- str -->
          {{ if eq . "title" "description" "lead" "matrix_identifier"
            "matrix_username" "github_username" "gitlab_username"
            "gitea_profile_url" "email_address" "website_url" "images"
            "contributors" "avatar" "mastodon_profile_url"
          }}
            <code>str</code>
          {{ end }}
          <!-- int -->
          {{ if eq . "weight" }}<code>int</code>{{ end }}
          <!-- datetime -->
          {{ if eq . "date" "lastmod" }}
            {{ $dt = true }}
            <code>datetime</code>
          {{ end }}
          <!-- bool -->
          {{ if eq . "draft" "matrix_moderator" "matrix_ex_moderator"
            "website_developer" "website_content" "bot" "toc" "math"
          }}
            <code>bool</code>
          {{ end }}
          <!-- structure -->
          {{ if eq . "menu" }}
            <code>structure</code>
          {{ end }}
          <!-- blog_post -->
          {{ if eq . "blog_post" }}
            <code>str</code>
          {{ end }}
          <!-- url -->
          {{ if eq . "url" }}
            <code>str</code>
          {{ end }}
        </td>
        <td>
          <!-- title -->
          {{ if eq . "title" }}The title of the page or ressource{{ end }}
          <!-- description -->
          {{ if eq . "description" }}
            The page description, normally for SEO
          {{ end }}
          <!-- lead -->
          {{ if eq . "lead" }}
            The page description shown after the title or in cards
          {{ end }}
          <!-- date -->
          {{ if eq . "date" }}The datetime the page was created{{ end }}
          <!-- contributors -->
          {{ if eq . "contributors" }}
            {{ $contrib = true }} A list of contributors
          {{ end }}
          <!-- lastmod -->
          {{ if eq . "lastmod" }}The datetime the page was modified. Should be the same as <code>date</code> when the creating a new page{{ end }}
          <!-- draft -->
          {{ if eq . "draft" }}
            <code>flase</code> shows the page, <code>true</code> hides the page,
            as it does not exist
          {{ end }}
          <!-- weigth -->
          {{ if eq . "weight" }}
            The weight, or priority of the page for page sorting
          {{ end }}
          <!-- images -->
          {{ if eq . "images" }}
            {{ $image = true }} Images, which will be converted and moved to the
            static directory. Remember to add every image you used here
          {{ end }}
          <!-- matrix_identifier -->
          {{ if eq . "matrix_identifier" }}
            The matrix user identifier e.g.
            <code>"@michael:michaelsasser.org"</code>
          {{ end }}
          <!-- matrix_username -->
          {{ if eq . "matrix_username" }}
            The matrix nickname e.g.
            <code>"Michael Sasser"</code>
          {{ end }}
          <!-- matrix_moderator -->
          {{ if eq . "matrix_moderator" }}
            <code>true</code>, when the user is a moderator; <code>false</code>,
            when not
          {{ end }}
          <!-- matrix_ex_moderator -->
          {{ if eq . "matrix_ex_moderator" }}
            <code>true</code>, when the user was a moderator; <code>false</code>,
            when not
          {{ end }}
          <!-- website_content -->
          {{ if eq . "website_content" }}
            <code>true</code>, when the user is a website content creator;
            <code>false</code>, when not
          {{ end }}
          <!-- website_developer -->
          {{ if eq . "website_developer" }}
            <code>true</code>, when the user is a website developer;
            <code>false</code>, when not
          {{ end }}
          <!-- github_username -->
          {{ if eq . "github_username" }}
            The GitHub username of that user e.g.
            <code>"MichaelSasser"</code>
          {{ end }}
          <!-- gitlab_username -->
          {{ if eq . "gitlab_username" }}
            The GitLab username of that user e.g.
            <code>"MichaelSasser"</code>
          {{ end }}
          <!-- gitea_profile_url -->
          {{ if eq . "gitea_profile_url" }}
            The URL to your Gitea profile e.g.
            <code>"https://mygitea.org/MichaelSasser"</code>
          {{ end }}
          <!-- mastodon_profile_url -->
          {{ if eq . "mastodon_profile_url" }}
            The Mastodon URL of that user e.g.
            <code>"https://fosstodon.org/@michaelsasser"</code>
          {{ end }}
          <!-- website -->
          {{ if eq . "website" }}
            An external website URL
            <code>"https://MichaelSasser.org"</code>
          {{ end }}
          <!-- website_url -->
          {{ if eq . "website_url" }}
            An external website URL
            <code>"https://MichaelSasser.org"</code>
          {{ end }}
          <!-- menu -->
          {{ if eq . "menu" }}
            A structure which describes the path to the parent menu
          {{ end }}
          <!-- toc -->
          {{ if eq . "toc" }}
            <code>true</code>, when a table of content should be created for
            that site; <code>false</code>, when not
          {{ end }}
          <!-- floating_image -->
          {{ if eq . "floating_image" }}
            A image, which should be placed floating next to the content
          {{ end }}
          <!-- floating_image_width -->
          {{ if eq . "floating_image_width" }}
            The width of the image in percent of the pages width
          {{ end }}
          <!-- floating_image_position -->
          {{ if eq . "floating_image_position" }}
            The position of the image, which can be either left or right
          {{ end }}
          <!-- floating_image_caption -->
          {{ if eq . "floating_image_caption" }}
            The caption the image should have
          {{ end }}
          <!-- header_image -->
          {{ if eq . "header_image" }}
            A image, which will be placed between the header and the lead with a
            100% width
          {{ end }}
          <!-- blog_post -->
          {{ if eq . "blog_post" }}
            The title of a blog post, which is available on that subject
          {{ end }}
          <!-- avatar -->
          {{ if eq . "avatar" }}
            An image, which is used as avatar from <code>images</code>
          {{ end }}
          <!-- email_address -->
          {{ if eq . "email_address" }}
            An email address, which will be public in your contributor profile
          {{ end }}
          <!-- url -->
          {{ if eq . "url" }}
            The URL the page will be reachable.
          {{ end }}
          <!-- bot -->
          {{ if eq . "bot" }}
            This user is a bot
          {{ end }}
          <!-- math -->
          {{ if eq . "math" }}
            This page contains LaTeX math. This option preloads the font and
            includes the KaTeX script in the script footer.
          {{ end }}
        </td>
      </tr>
    {{ end }}
  </tbody>
</table>

You will find a complete list and how to use them inside the site in the
<a href="https://gohugo.io/variables/">Hugo docs →</a>

{{/*
<!-- Image Alert -->
{{ if eq $image true }}
<div class="bd-callout bd-callout-info" role="alert">
  <h5>Images</h5>
  <br /><br />
  Remember to add every image you used to the <i>images</i> variable in the
  front matter as described in the
  </div>
{{ end }}


<!-- Image Alert -->
{{ if eq $contrib true }}
<div class="bd-callout bd-callout-info" role="alert">
  <h5>Contributors</h5>
  <br /><br />
  Remember to create your contributors site add your name in the
  <i>contributors</i> variable in the front matter as described in the
  <a href="/docs/contributing/project_structure/#the-contributors">
    contributors section</a
  >.
</div>
{{ end }}
*/}}


<!-- The datetime type -->
{{ if eq $dt true }}
  <h3>The Datetime Type</h3>
<p>The date and time according to
    <abbr title="ISO 8601 provides a standard set of date and time format representations for information interchange, in order to minimize the risk of misinterpretation, confusion and their consequences">
      ISO 8601
    </abbr>.
  The following table shows the extended format specified in ISO 8601 we
  use for our website to specify, when e.g. a page was created or edited.
  It has three parts:

  <ul>
    <li>the date</li>
    <li>the time, including it's designator <code>T</code></li>
    <li>the timezone offset</li>
  </ul>

  We would prefere if you would use your local time together with the timezone
  offset (in this case it is mandatory),
  but you can also enter the time in UTC without the timezone offset.

  <table class="table">
    <thead>
      <tr>
        <th>Value</th>
        <th>Optional</th>
        <th>Description</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><code>2021</code></td>
        <td>No</td>
        <td>Year</td>
      </tr>
      <tr>
        <td><code>07</code></td>
        <td>No</td>
        <td>Month</td>
      </tr>
      <tr>
        <td><code>08</code></td>
        <td>No</td>
        <td>Day of the month</td>
      </tr>
      <tr>
        <td><code>T</code></td>
        <td>No</td>
        <td><code>T</code> is a designator, which indicates the start of the time representation</td>
      </tr>
      <tr>
        <td><code>12</code></td>
        <td>No</td>
        <td>Hour</td>
      </tr>
      <tr>
        <td><code>34</code></td>
        <td>No</td>
        <td>Minute</td>
      </tr>
      <tr>
        <td><code>56</code></td>
        <td>No</td>
        <td>Second</td>
      </tr>
      <tr>
        <td><code>+</code> or <code>-</code></td>
        <td>Yes</td>
        <td>
          <code>+</code> for a positive or <code>-</code> a negative timezone
          offset
        </td>
      </tr>
      <tr>
        <td><code>01</code></td>
        <td>Yes</td>
        <td>Timezone offset in hours</td>
      </tr>
      <tr>
        <td><code>02</code></td>
        <td>Yes</td>
        <td>Timezone offset in minutes</td>
      </tr>
    </tbody>
  </table>

  <h4>Formatting Examples</h4>
  <p>The following example uses the values from the table to show the format.
  It does not use the actual UTC. If you are not using the timezone offset,
  you must calculate UTC yourself.</p>
  <ul>
    <li>
      Example with timezone offset: <code>2021-07-08T12:34:56+01:02</code>
    </li>
    <li>Example without timezone offset: <code>2021-07-08T12:34:56</code></li>
  </ul>
{{ end }}


<h3>Header Example</h3>

Remember, the front matter is a <code>YAML</code> structure embedded into the
Markdown file. The <code>---</code> delimiters signal Hugo that this is a front
matter in the <code>YAML</code> format. Here is a generated example, how the
front matter might look like:

<!-- Example -->
<pre><button class="btn btn-copy"></button><code class="language-yaml">
---
{{- range $fields }}
{{ if eq . "title" -}}                  {{- . -}}: "MyTitle"                           {{- end -}}
{{ if eq . "images" -}}                 {{- . -}}: ["avatar.svg" "foo.svg" "bar.svg"]  {{- end -}}
{{ if eq . "description" -}}            {{- . -}}: "A description of the page content" {{- end -}}
{{ if eq . "lead" -}}                   {{- . -}}: "A lead to the page content"        {{- end -}}
{{ if eq . "weight" -}}                 {{- . -}}: 50                                  {{- end -}}
{{ if eq . "contributors" -}}           {{- . -}}: ["UserA" "UserB" "UserC"]           {{- end -}}
{{ if eq . "matrix_identifier" -}}      {{- . -}}: "@user:matrix.org"                  {{- end -}}
{{ if eq . "matrix_username" -}}        {{- . -}}: "UserName"                          {{- end -}}
{{ if eq . "github_username" -}}        {{- . -}}: "UserName"                          {{- end -}}
{{ if eq . "gitlab_username" -}}        {{- . -}}: "UserName"                          {{- end -}}
{{ if eq . "gitea_profile_url" -}}      {{- . -}}: "https://mygitea.org/UserName"      {{- end -}}
{{ if eq . "date" "lastmod" -}}         {{- . -}}: 2021-10-08T14:48:42+01:00           {{- end -}}
{{ if eq . "draft" -}}                  {{- . -}}: false                               {{- end -}}
{{ if eq . "matrix_moderator" -}}       {{- . -}}: false                               {{- end -}}
{{ if eq . "matrix_ex_moderator" -}}    {{- . -}}: false                               {{- end -}}
{{ if eq . "website_content" -}}        {{- . -}}: false                               {{- end -}}
{{ if eq . "website_developer" -}}      {{- . -}}: false                               {{- end -}}
{{ if eq . "toc" -}}                    {{- . -}}: false                               {{- end -}}
{{ if eq . "menu" -}}                   {{- . -}}: [...]  # see below                  {{- end -}}
{{ if eq . "floating_image" -}}         {{- . -}}: "foo.svg"                           {{- end -}}
{{ if eq . "floating_image_width" -}}   {{- . -}}: 50                                  {{- end -}}
{{ if eq . "floating_image_position" -}}{{- . -}}: "right"                             {{- end -}}
{{ if eq . "floating_image_caption" -}} {{- . -}}: "A optional caption line"           {{- end -}}
{{ if eq . "header_image" -}}           {{- . -}}: "foo.svg"                           {{- end -}}
{{ if eq . "blog_post" -}}              {{- . -}}: "Hello Wrold"                       {{- end -}}
{{ if eq . "avatar" -}}                 {{- . -}}: "avatar.svg"                        {{- end -}}
{{ if eq . "email_address" -}}          {{- . -}}: "[email protected]"                {{- end -}}
{{ if eq . "website_url" -}}            {{- . -}}: "https://domain.tld"                {{- end -}}
{{ if eq . "mastodon_profile_url" -}}   {{- . -}}: "https://domain.tld/@foo"           {{- end -}}
{{ if eq . "url" -}}                    {{- . -}}: "/wiki/MyTitle"                     {{- end -}}
{{ if eq . "bot" -}}                    {{- . -}}: true                                {{- end -}}
{{ if eq . "math" -}}                   {{- . -}}: true                                {{- end -}}
{{- end -}}
# This is an example for a comment in YAML
---
</code></pre>

Download

Copy the source code above or use the download link below to use this file on your website according to the license.

Variable Structure Shortcode
variable_structure.html ❘ 15.52 KB
md5 8fb3c738705e763f43dc0af8fa2090fb
sha1 0c205f2a6ef7f2d3ed8ac8be939823266f740e1d
sha256 5e7e60e3db762f1a4e398f9714a7a25d1d521d1c5815c234730b865d76a4157c

Categories	Contributors
Help, Contribute and Shortcode	Michael Sasser

Help:Shortcode Variable Structure

Parameters #

Examples #

Header Example

Code #

HTML #

Download #

Categories

Contributors

Parameters

Examples

Code

HTML

Download