Hugo ショートコードの練習: バンドルファイル (複数言語のファイルと添付ファイルは同じページバンドルディレクトリに配置されます)

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

多言語サイトでは、記事の本文に同じ添付ファイル (PDF、設定ファイル、スクリプトなど) が含まれることがよくあります。ダウンロードリンクが言語バージョンごとに手動で管理されている場合、後でリンクの不一致やファイルの損失が簡単に発生する可能性があります。

この記事では、この問題を解決するために、直接再利用可能な Hugo ショートコード bundle-file を提供します。

ターゲット

同じ記事の多言語ファイルと添付ファイルを同じページバンドルディレクトリに配置します。次に例を示します。

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

これにより、リソースの再利用を最大限に高め、重複コピーを減らすことができます。 Hugo がそれを HTML に変換すると、コピーを繰り返すことなく、複数の言語が同じ添付ファイルをポイントできることが期待されます。

ショートコードの実装

ファイル: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 の動作は単純です。

現在のページのリソースからのファイルの検索を優先します。
現在の言語が見つからない場合は、他の翻訳ページに移動して、同じ名前のファイルの検索を続けます。
見つかった場合はダウンロードリンクが出力されます。見つからない場合は、見つからないファイル名を入力するよう求められます。

パラメータの説明

name: 添付ファイル名、必須。
text: リンク表示テキスト、オプション。送信されない場合は、デフォルトで name が表示されます。

使用例

`1`	`Missing file: demo.pdf`

text が渡されない場合:

`1`	`Missing file: demo.pdf`

公開前に確認してください

添付ファイルは記事と同じページバンドル内にあります。
name は実際のファイル名とまったく同じです (大文字と小文字を含む)。
リンクをクリックしてローカルでプレビューし、アクセスできることを確認します。

要約する

bundle-file は、多言語記事の添付リンク管理を「パスの手動管理」から「ルールに従った自動検索」に変更します。ナレッジベースや技術ブログの長期メンテナンスの場合、これによりリンクエラー率が大幅に削減され、リリース前のトラブルシューティングのコストが削減されます。

Shortcode on KnightLiブログ