Skip to content

Includes

Use include to insert a file, param to print a site parameter, and comment to remove a note from every output.

include inserts another file’s content into the page. param prints a page or site parameter. comment removes a passage. Use them for fragments or constants shared by multiple pages. For example, use include for installation steps on three pages and param for a version number on dozens of pages. You then edit one source. Keep content used by only one page on that page.

Shortest form

include takes one required parameter, file:

Source
{{< include file="parts/install-oink.md" >}}

The included file contains ordinary Markdown under assets/:

assets/parts/install-oink.md
Installing OINK into an existing Hugo site takes three commands:

```sh
hugo mod init github.com/you/your-site
hugo mod get github.com/pgsty/oink
hugo server
```

> [!NOTE]
> `hugo mod get` needs Go on the machine; an offline archive or a submodule does not.

The current release is {{< param version >}}.

The result is the same as writing the content here. The code block has a copy button, and the callout displays normally.

Installing OINK into an existing Hugo site takes three commands:

hugo mod init github.com/you/your-site
hugo mod get github.com/pgsty/oink
hugo server
Note

hugo mod get needs Go on the machine; an offline archive or a submodule does not.

The current release is v1.5.1.

An included file is not a separate page. It has no sidebar entry, translation pairing, or URL.

Where the file comes from

file resolves in this order. The first match takes precedence:

Order Looked up as Written as
1 A page resource — a file in this page’s bundle file="config.yaml"
2 A global resource under assets/ file="snippets/dsn.txt"
3 A file under content/: a leading / is the content root, otherwise relative to the page’s directory file="notes/caveat.md", file="/shared/notice.md"

If no source matches, or the path contains .., the include warns and emits nothing. Review the warning and rendered fallback before publication. Include reads only from content/ and assets/.

Markdown fragments are read as source. Use the file’s actual disk name. Page resources in step 1 have one exception. Hugo attaches language-suffixed resources such as notice.zh.md under a name without the language suffix. Requesting notice.md from a bundle therefore gives include rendered HTML instead of source. The Markdown output can then contain <div class="td-code">. Under assets/ and content/, the written name identifies the exact file. Non-Markdown files (.yaml, .sh, .txt) have no such distinction.

Each language of this page includes its own fragment. English uses assets/parts/install-oink.md; Chinese uses assets/parts/install-oink.zh.md. Storing fragments under assets/ instead of the page bundle lets both languages retrieve source with the written filename.

Including code files

code=true displays the file as a code block. lang= sets its highlighting language. Use a real repository file to keep the documentation consistent with that file.

Source
{{< include file="parts/module.yml" code=true lang="yaml" >}}
module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: 0.168.0

Included code and fences share the same pipeline for highlighting, line numbers, and copying. You cannot pass fence attributes such as title=, collapse, or hl_lines= through include. If you need them, write an ordinary code block.

What a fragment can contain

Fragments use page-level Markdown in the current page’s context. They support callouts, tables, lists, images, steps, and shortcodes. The example fragment’s last line, “The current release is v0.8.1”, comes from {{< param version >}} expanded on this page.

If two pages include the same fragment, each renders it separately. Each generates its own heading anchors and code-block IDs without collisions.

What makes a good fragment

Use fragments for installation commands, connection strings, support matrices, and legal notices that must change on all pages together. Keep content used by only one page on that page.

Printing a site parameter

param prints one parameter. It checks page front matter first, then site configuration, following Hugo’s .Param rule.

Source
This site publishes {{< param version >}}, copyright from {{< param copyright.from_year >}},
and this page's front matter says `pigsty_pg_major: 18`, which reads back as {{< param pigsty_pg_major >}}.

This site publishes v1.5.1, copyright from 2026, and this page’s front matter says pigsty_pg_major: 18, which reads back as 18.

Join nested keys with .. For example, copyright.from_year reads params.copyright.from_year. Missing parameters and values that are maps or lists warn and print nothing. Review the warning and rendered fallback before publication.

Parameters inside commands, tables and links

param emits escaped plain text. It can appear in code fences, table cells, or link targets. For example, use it for a version number in an installation command:

Source
```sh
hugo mod get github.com/pgsty/oink@{{< param tdVersion.latest >}}
```

| Item | Value |
| --- | --- |
| Current version | {{< param version >}} |
| Hugo floor | {{< param hugoMinVersion >}} |

[Release notes](https://github.com/pgsty/oink/releases/tag/{{< param tdVersion.latest >}})
hugo mod get github.com/pgsty/[email protected]
Item Value
Current version v1.5.1
Hugo floor 0.168.0

Release notes

Configuration defines site parameters. Front matter defines page parameters.

Notes deleted at build time

A comment body appears in none of the four outputs: HTML, print, Markdown, or RSS. HTML comments remain in page source and reach llms.txt.

Source
Since PostgreSQL 18, `pg_stat_io` breaks out WAL statistics.

{{< comment >}}
TODO: after v0.5 ships, bump the version above to 19 and add a pg_stat_io screenshot.
This text reaches no output at all, llms.txt included.
{{< /comment >}}

Verify the dashboards on a test database before upgrading.

Since PostgreSQL 18, pg_stat_io breaks out WAL statistics.

Verify the dashboards on a test database before upgrading.

A comment exists between those paragraphs, but it does not appear in the page source.

Output

Output include (Markdown) include code=true param comment
HTML The fragment renders as normal content Highlighted code block + copy button Escaped plain text nothing
Print As HTML As HTML, without the copy button As HTML nothing
Markdown The fragment’s source, as written A source fence The value itself nothing
RSS As HTML As HTML As HTML nothing

Markdown output preserves fragment source instead of rendered HTML. Its shortcodes remain as {{< param version >}}. This is the intended source-preserving behavior. None of these three shortcodes loads a script.

Parameter reference

include (named parameters only):

file , path (required) , default—
Resolution order in Where the file comes from; a .., missing file, or empty value warns and emits nothing
code , boolean , defaultfalse
true renders as a code block; quoted code="true" warns and includes ordinary content
lang , string , default—
Code language; without code=true it warns and is ignored

Other parameter names warn and are ignored. The message identifies the file and line.

param (one positional parameter):

parameter name , string (required) , default—
Nested keys join with .; page front matter first, then site params; missing or non-scalar values warn and print nothing

comment takes no parameters. Use opening and closing shortcodes. All content between {{< comment >}} and {{< /comment >}} is discarded.

Limits

  • include is not a template. You cannot pass variables, include conditionally, or supply code-block fence attributes such as title= or collapse. For platform variants, create two fragments and use tabs.
  • You maintain fragment languages. include has no language fallback and uses the exact written path. You can share a fragment across languages, as this page’s Chinese translation includes the same English file. Alternatively, write one fragment per language and use its path on the corresponding page.
  • param prints only scalars. Put structured data, such as version matrices or download lists, in data/ and use the matching component.
  • comment discards content on every build. To temporarily unpublish a whole page, use draft: true.
  • Do not use include to create an index page. If a page needs ten fragments, give readers ten links instead.
  • Code blocks — every fence attribute, and the pipeline include code=true reuses
  • Tabs — per-platform or per-language fragments
  • Configuration — the site parameters param can reach
  • Front matter — page parameters, which win over site configuration