Hugo's printUnusedTemplates option is very useful for keeping a site's template tree clean. I would like to request a small companion mechanism to mark some templates as intentionally allowed to remain unexecuted during successful builds.
Current behavior
printUnusedTemplates reports templates whose execution count is zero during the build. This is a good default behavior and I do not think it should change.
However, some templates are intentionally only used on error paths or other rare conditional paths. For example, a site may have a shared partial used to fail fast with consistent diagnostics:
{{ partial "fail.html" (dict
"message" "missing required parameter"
"location" "..."
"fix" "..."
) }}
During a successful production build, this partial is not executed, so printUnusedTemplates reports it as unused even though it is intentionally part of the template system.
A site can work around this by calling the partial once with a no-op argument, but that feels like a workaround: it changes template execution only to satisfy the diagnostic check.
Proposal
Add a config option to exclude specific templates from printUnusedTemplates warnings, for example:
ignoreUnusedTemplates = [
"_partials/fail.html",
]
Glob patterns would also be useful, but exact template names alone would already solve the core problem:
ignoreUnusedTemplates = [
"_partials/fail.html",
"_partials/debug/*.html",
]
The important part is that this would not change the meaning of printUnusedTemplates: templates would still be considered "used" only when actually executed. The option would only suppress warnings for templates the project explicitly declares as intentionally retained.
Use cases
This would help with templates that are valid and intentional but may not execute in a successful build:
- shared error/fail-fast partials
- debug-only partials
- optional theme extension points
- templates used only by certain content states, languages, output formats, or build environments
- rare shortcode/render-hook variants that a theme wants to keep available
Alternatives considered
Changing printUnusedTemplates to count static references as usage would make the warning less precise, and could hide templates that are referenced but never actually reached.
A template-local marker such as a comment directive could also work, but a config allowlist seems simpler and keeps the diagnostic policy in site configuration.
Hugo's
printUnusedTemplatesoption is very useful for keeping a site's template tree clean. I would like to request a small companion mechanism to mark some templates as intentionally allowed to remain unexecuted during successful builds.Current behavior
printUnusedTemplatesreports templates whose execution count is zero during the build. This is a good default behavior and I do not think it should change.However, some templates are intentionally only used on error paths or other rare conditional paths. For example, a site may have a shared partial used to fail fast with consistent diagnostics:
During a successful production build, this partial is not executed, so
printUnusedTemplatesreports it as unused even though it is intentionally part of the template system.A site can work around this by calling the partial once with a no-op argument, but that feels like a workaround: it changes template execution only to satisfy the diagnostic check.
Proposal
Add a config option to exclude specific templates from
printUnusedTemplateswarnings, for example:Glob patterns would also be useful, but exact template names alone would already solve the core problem:
The important part is that this would not change the meaning of
printUnusedTemplates: templates would still be considered "used" only when actually executed. The option would only suppress warnings for templates the project explicitly declares as intentionally retained.Use cases
This would help with templates that are valid and intentional but may not execute in a successful build:
Alternatives considered
Changing printUnusedTemplates to count static references as usage would make the warning less precise, and could hide templates that are referenced but never actually reached.
A template-local marker such as a comment directive could also work, but a config allowlist seems simpler and keeps the diagnostic policy in site configuration.