Hugo Fragments

Hugo is the static site generator that is used to build the new parts of the Infinite Ink website, including this page. I use the fragments below in some of Infinite Ink’s source files.

Page contents

Commenting in website source files

Commenting is useful for writing notes to yourself and for holding fragments that you have used in the past or may use in the future. To learn about the comment syntax of many languages, see Infinite Ink’s Commenting Code Cheatsheet.

‼︎

In a child block layout file, do not put a comment — or anything other than blank lines — outside a define-end container:

only blank lines here

{{ define "main" }}

   Go Template code and comments here

{{ end }}

only blank lines here

 

1. Commenting out code in layout files

In the Go Template language, which is also known as Go HTML, you can comment out code with the following single- or multi-line comment syntax.

{{/* Go HTML single-line comment */}}


{{/*
     Go HTML
     multi-line
     comment
*/}}

2. Commenting out non-code in layout files and Markdown content files

To comment out non-code (such as an English-language note to yourself) in a layout file or a Markdown content file, you can use the following single- or multi-line comment syntax.

<!--  HTML or Markdown single-line comment -->

<!--
    HTML or Markdown
    multi-line
    comment
-->
‼︎
Do not use these HTML-style comments to comment out Go Template code in a Hugo layout file. If you do, Hugo will process the code and potentially generate error messages or change the layout logic.

One-off shortcodes

Shortcodes are a way to use Go Template code within a Hugo content file. Reusable and one-off shortcodes usually live in the layouts/shortcodes/ directory but, starting with Hugo 0.52, you have the option to put a shortcode directly into a content file by using an “inline shortcode.” This is especially useful for one-off shortcodes such as the ones discussed in Fragment 3 and Fragment 4 below.

To use inline shortcodes you need to set enableInlineShortcodes to true in your Hugo config file by, for example, putting the following in your config.yaml.

enableInlineShortcodes: true

 

3. “Writing in Progress” inline shortcode

On Infinite Ink’s To-Do and Done Lists, in the section Writing in Progress, there is a list of articles that have not yet been published. For the public, this is a list of titles without links, but for me, when I am developing the Infinite Ink site with hugo server, this is a list of titles with links to these unreleased articles. I do this by putting my writing-in-progress articles in a directory named content/wip/[1][2] and by putting the following inline shortcode in Infinite Ink’s website-todo-done.asciidoc[3] content file.

{{< wip.inline >}}
    
<ul class="posts">

  {{ range where .Site.RegularPages.ByTitle "Section" "eq" "wip" }}

    <li>
  
      {{ if eq hugo.Environment "development" }}
    
        <a href="{{ .Permalink }}"><em>{{ .Title }}</em></a>
        
      {{ else }}  <!-- not development -->
    
          <em>{{ .Title }}</em>
    
      {{ end }}  <!-- end if-else -->
  
    </li>

  {{ end }}  <!-- end range -->

</ul>

{{< /wip.inline >}}

 

Note that I do things to ensure that no WIP[1] article is mentioned on any other Infinite Ink page. For example, the tag list in a WIP article’s front matter is commented out until it is no longer a WIP.

 

4. “Hugo version” inline shortcode

The Tools section of the About Infinite Ink page includes this list item:

  • hugo v0.68.3/extended

Each time hugo builds the Infinite Ink site, the part after “hugo ” is generated by the following fragment in Infinite Ink’s about.asciidoc[3] content file.

v{{< hv.inline >}}
  {{- hugo.Version -}}
{{< /hv.inline >}}/extended

 

💡︎
The dashes[4] in {{- and -}} tell hugo to remove whitespace around the output of hugo.Version.

Endnotes

Comments and reactions⁠💬


1. WIP can mean “work in progress” or “writing in progress.”
2. The front matter of some of Infinite Ink’s WIP articles include draft: true. Only the titles of the WIP articles that are not drafts are listed when I publish Infinite Ink’s To-Do and Done Lists page.
4. The Unicode name for “dash” (-) is hyphen-minus. Details are at Hyphen-minus - Wikipedia.

Comments and reactions💬

All comments are welcome including suggestions for improving this page, relevant links to other sites, and questions.