Hugo Shortcode Practice: bundle-file (Keep Multilingual Files and Attachments in One Page Bundle)

Sun, 29 Mar 2026 00:00:00 +0000

In multilingual sites, posts often share the same attachment files (for example, PDFs, config files, or scripts). If each language version maintains download links manually, link drift and missing files become common over time.

This article introduces a reusable Hugo shortcode, bundle-file, to solve this problem.

Goal

Keep multilingual post files and attachments in the same Page Bundle directory, for example:

content/post/2026/03/09/01/
  index.zh-cn.md
  index.zh-tw.md
  index.en.md
  demo.pdf
  script.sh

This maximizes reuse and avoids duplicate copies. After Hugo builds HTML pages, all language versions should point to the same attachment instead of duplicated files.

Shortcode Implementation

File: layouts/shortcodes/bundle-file.html

{{- $name := .Get "name" -}}
{{- $text := .Get "text" | default $name -}}

{{- $res := .Page.Resources.GetMatch $name -}}
{{- if not $res -}}
  {{- range .Page.AllTranslations -}}
    {{- if not $res -}}
      {{- $tmp := .Resources.GetMatch $name -}}
      {{- if $tmp }}{{ $res = $tmp }}{{ end -}}
    {{- end -}}
  {{- end -}}
{{- end -}}

{{- if $res -}}
<a href="{{ $res.RelPermalink }}">{{ $text }}</a>
{{- else -}}
<span>Missing file: {{ $name }}</span>
{{- end -}}

bundle-file works with a simple strategy:

Look up the file in current page resources first.
If not found, search the same file name in other translated pages.
Output a download link when found, or show a missing-file message when not found.

Parameters

name: attachment filename (required)
text: link label (optional); defaults to name

Usage Example

`1`	`Missing file: demo.pdf`

Without text:

`1`	`Missing file: demo.pdf`

Pre-publish Checklist

Put attachments and post files in the same Page Bundle.
Ensure name exactly matches the real filename (including case).
Click links in local preview to confirm accessibility.

Summary

bundle-file turns multilingual attachment handling from manual path maintenance into rule-based automatic lookup. For long-lived knowledge bases and technical blogs, this reduces broken-link risk and pre-release review time.