Include-file shortcode for including files with shortcode calls

tips & tricks
1

Following is a simplified version of our include shortcode for including Markdown (or HTML) content files from other content files:

include.html

{{- $includes_dir := (.Get "d") | default .Site.Params.includes_dir -}}
{{- $include_file := printf "%s/%s" $includes_dir (.Get "f") -}}

{{- with .Site.GetPage $include_file -}}
  {{- .Content | markdownify -}}
{{- end -}}

In config.toml, we set an includes_dir site Params variable to a default includes content directory:

[Params]
  includes_dir = "_includes"

NOTES

  • With readFile (as opposed to getPage), shortcode calls in the included file aren’t processed.
    Also, readFile accepts a file path within the Hugo root directory while GetPage accepts a relative file path within the configured content directory.

  • PROBLEM: Initially, adding a shortcode call at the start of the included file (before any text or standard Markdown code) produced a Hugo runtime error:

    invalid character '{' looking for beginning of object key string for <include file path>.

    With v0.48 of Hugo, adding an empty HTML comment before the shortcode call eliminated the error; but with v0.52 or v0.53, this didn’t help and even the HTML comment on its own produced a similar error.

    SOLUTION: We found that adding a metadata section at the start of the included file (as is the standard practice for Hugo content files) eliminates the error, even if it’s an empty section (i.e., just two --- lines). (I’m guessing the different behavior between v0.48 and v0.52+ might be related to the support for defining inline shortcodes in content files, which was added in Hugo v0.52.)

  • For information about include-file shortcode-calls context issues that we encountered and our solution (related to our multi-version site design), see Include-file shortcode context issues.

  • For reflecting include-file headings in the including file’s page mini TOC, see my answer on the Shortcode processing order thread and the
    Shortcode processing order - #8 by sharonl tips post that it references.

1 Like