More about the v0.144.0 release

tips & tricks
1

The release notes for v0.144.0 highlight the technical changes, but I want to provide some additional context about the value these changes bring.

New permalink tokens

Hugo’s permalink patterns, used in your site configuration or the url front matter field, utilize tokens like :title and :slug. This release replaces the deprecated :filename and :slugorfilename tokens with :contentbasename and :slugorcontentbasename, respectively.

This change is significant because the new tokens can be used with section, taxonomy, and term pages—something previously restricted to regular pages. They also extend to pages generated from data using content adapters.

Automatic IDs for description list terms

Hugo, by default, uses Goldmark’s “definition list” extension to render Markdown like this:

term one
: The description for term one.

term two
: The description for term two.

Into standard HTML description lists (dl):

<dl>
  <dt>term one</dt>
  <dd>The description for term one.</dd>
  <dt>term two</dt>
  <dd>The description for term two.</dd>
</dl>

This release introduces the parser.autoDefinitionTermID setting. Enabling this option in your site configuration will automatically add id attributes to the dt elements:

<dl>
  <dt id="term-one">term one</dt>
  <dd>The description for term one.</dd>
  <dt id="term-two">term two</dt>
  <dd>The description for term two.</dd>
</dl>

This allows direct linking to specific terms within the description list, a valuable feature for documentation sites. You can then add anchor links next to each term using JavaScript, either custom or a library such as AnchorJS.

Each id corresponds to an element in the slice returned by Page.Fragments.Identifiers. To ensure uniqueness, duplicate ids among headings and dt elements are handled by appending a suffix like -1 or -2.

We’re transitioning our documentation to use this new feature. For example, see the options list on the js.Build page.

Passthrough render hook improvement

When a site or theme author creates a passthrough render hook, the Position method will now report the exact location in the Markdown file, including filename, line number, and column. This makes debugging LaTeX markup for mathematical equations and expressions much easier.

Render chemical equations and expressions

The transform.ToMath template function renders mathematical equations and expressions written in LaTeX. This release expands its capabilities to include chemical equations and expressions. For example, the following LaTeX markup:

$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$

will be rendered as:

image

ContentTypes in site configuration

Hugo supports six content formats: Markdown, HTML, Emacs Org Mode, AsciiDoc, Pandoc, and reStructuredText. These can be used as either page content or page resources. Consider this page bundle example:

content/
└── example/
    ├── index.md  <-- content
    ├── a.adoc    <-- page resource, ResourceType = page
    ├── b.html    <-- page resource, ResourceType = page
    ├── c.org     <-- page resource, ResourceType = page
    ├── d.pdc     <-- page resource, ResourceType = page
    ├── e.rst     <-- page resource, ResourceType = page
    ├── f.jpg     <-- page resource, ResourceType = image
    └── g.png     <-- page resource. ResourceType = image

The index.md file is the page’s content, while the other files are resources. Files a through e have a ResourceType of page (content), while f and g are image resources.

Before v0.123.0, Hugo published all page resources. Since v0.123.0, Hugo only publishes resources not having a ResourceType of page. To publish files with a ResourceType of page, you must explicitly access them as resources and invoke their RelPermalink, Permalink, or Publish methods. This means, for example, a static HTML file in a page bundle is no longer automatically copied.

v0.144.0 introduces the contentTypes top-level configuration key. The default is:

contentTypes:
  text/asciidoc: {}
  text/html: {}
  text/markdown: {}
  text/org: {}
  text/pandoc: {}
  text/rst: {}

This configuration treats resources with these content types (media types) as content and prevents their automatic publication. To only treat Markdown files as content and automatically publish the others, configure your site like this:

contentTypes:
  text/markdown: {}

With this configuration, HTML, Emacs Org Mode, AsciiDoc, Pandoc, and reStructuredText files will be published when the site is built.

Acknowledgement

The new features, fixes, and performance improvements in v0.144.0, along with recent documentation site improvements, represent a significant investment of over 200 person-hours. A huge thank you to @bep for making this release possible.

23 Likes