ブログ記事を執筆していると、「この用語や手順については、以前別の記事で詳しく解説しているからそちらを読んでほしい！」と他のページを紹介したくなる場面がよくあります。

この記事では、HugoのMarkdown記事内にサラッと**内部リンク（サイト内の別記事へのリンク）**を貼るための、安全で正しい指定方法を解説します。

1. リンクの貼り方：2つのパターン

リンクを貼るには、主に2つの方法があります。
結論から言うと、パターンA（Hugoの機能を使う方法）が圧倒的にオススメです！

パターンA：Hugoの ref 機能を使う（推奨）✅

記事の ファイル名 を指定してリンクする方法です。

インストール方法は[Step 1の記事]({{< ref "posts/01-intro-install.md" >}})を見てね。

メリット:

  • サイトのドメインが変わっても（localhost → example.com）、リンク切れしません。
  • ファイル名さえ合っていれば、Hugoが自動的に正しいURLを探してくれます。

パターンB：URLを直接書く（非推奨）❌

ブラウザのアドレスバーのURLをそのままコピペする方法です。

インストール方法は[Step 1の記事](http://localhost:1313/posts/01-intro-install/)を見てね。

デメリット:

  • 公開するときにドメインが変わると、 全てのリンクが切れてしまいます！
  • localhost でしか動かないサイトになってしまうので、やめましょう。

2. ファイルの指定方法（パスの書き方）

ref を使うとき、「どのファイルを指定すればいいの？」と迷うかもしれません。
基本は 「記事ファイル（.md）の場所」 を書きます。

基本：ファイル名だけでOK

ファイル名がサイト内でユニーク（被りがない）なら、ファイル名だけで探してくれます。

[記事リンク]({{< ref "01-intro-install.md" >}})

フォルダが階層になっている場合

例えば、content/diary/2024/my-diary.md のような深いフォルダにある記事の場合も、基本はファイル名だけでOKです。

[日記へのリンク]({{< ref "my-diary.md" >}})

もし、別のフォルダに同じファイル名（content/news/hello.md と content/blog/hello.md）がある場合は、フォルダ名を含めて区別します。

[ニュースのハロー]({{< ref "news/hello.md" >}})
[ブログのハロー]({{< ref "blog/hello.md" >}})

これスラッシュ(/)から始めてもいいの？
はい、OKです！
{{< ref "/posts/01-intro.md" >}} のように、先頭にスラッシュをつけてもHugoはちゃんと認識してくれます。Obsidianなどと互換性を持たせたい場合に便利ですね。

⚠️ 注意：refを使わずに .md へリンクしない！
[リンク](/posts/abc.md) とそのまま書いても、ページは見つかりません（404エラー）。
ブラウザは「変換されたHTMLのURL」しか知らないからです。

※ [リンク](/posts/abc/) のように「変換後のURL」を直接書けば動きますが、URLが変わった瞬間にリンク切れするのでおすすめしません。必ず ref を通して、Hugoに正しいURLへ変換してもらいましょう。

3. 記事カード風にするテクニック

ちょっと目立たせたいときは、引用記法を使うのも手です。

> **あわせて読みたい**
> 
> [【Step 2】自分だけの城を築こう！新規サイトとテーマの作成]({{< ref "posts/02-create-site.md" >}})

あわせて読みたい

【Step 2】自分だけの城を築こう！新規サイトとテーマの作成

こうすると、ブログカードっぽくなってクリック率が上がるかも！？ぜひ読者をサイト内で迷わず案内する導線を作ってください！🗺️

正しい内部リンクの設定でサイトの回遊性を高めよう

Hugoの ref ショートコードを活用することで、開発環境（localhost）と本番環境（公開ドメイン）の違いによるリンク切れを防ぐことができます。
また、将来パーマリンクの構造を変えたとしても自動的に追従してURLを生成してくれるため、メンテナンスの手間が大幅に省けます。内部リンクを貼る際は、URL直打ちではなく必ずこの方法を利用するようにしましょう。