Markdownのリンクが開かない原因と正しい書き方

まず正しいリンク記法か確認する

Markdownの基本的なリンクは、角括弧に表示する文字、丸括弧に移動先を書きます。

[公式サイトを開く](https://example.com)

!を先頭に付けると画像記法になります。括弧が全角、閉じ括弧がない、表示名とURLの順番が逆、といった場合はリンクとして認識されません。実際に使うMarkdownレンダラでHTMLへ変換し、リンクとして表示されてクリックできるか確認します。

原因1：URLにhttps://がない

example.comだけを書くと、現在のページから見た相対パスとして扱われる場合があります。外部サイトへのリンクは、原則としてhttps://から始まる完全なURLを指定します。

<!-- 外部リンク -->
[Example](https://example.com/docs)

<!-- 同じサイト内のリンク -->
[使い方を見る](/ja/blog/usage-guide)

URLをブラウザへ直接貼り付け、目的のページが開くかも確認します。リンク先が移動・削除されている場合、Markdown側が正しくても404になります。

原因2：URLに空白や括弧が含まれている

URL内の空白、日本語、丸括弧などは、処理系によって途中までしかリンクにならないことがあります。可能なら正しくURLエンコードされたURLを使用します。コピー元の文書から、見えない改行や末尾の句読点が混ざることもあります。

URLが長い場合でも、本文へURLをそのまま表示せず、内容が分かるリンク名を付けます。「こちら」より「Markdown PDFの改ページガイド」のような名前の方が、読み手にもリンク先が伝わります。

原因3：相対リンクの基準が変わった

次のリンクは、現在のファイルから見たdocs/setup.htmlを開きます。

[セットアップ手順](docs/setup.html)

Markdownを別フォルダへ移動したり、1ファイルのHTMLとして保存したりすると、基準位置が変わってリンク切れになることがあります。配布先にも同じフォルダ構成を含めるか、公開済みページの絶対URLへ置き換えます。

PC内のfile:///Users/...やC:\...を指定しても、受け取った人の端末には同じファイルがありません。ローカル絶対パスは配布文書に使わないようにします。

原因4：見出しへのリンク先IDが一致しない

ページ内の見出しへ移動するリンクは、一般に#見出し-idの形を使います。

[注意事項へ移動](#注意事項)

## 注意事項

見出しからIDを作るルールはMarkdown処理系によって異なります。空白、記号、日本語、大文字小文字、同名見出しの連番などが原因で一致しないことがあります。変換後のHTMLを開き、実際の見出しIDを確認してください。

見出し名を変更するとリンクも更新が必要です。同じ見出し名を何度も使わず、意味の分かる固有の見出しにするとリンクが安定します。

HTMLでは開くのにPDFでは開かない場合

PDF生成方法によっては、外部リンクやページ内リンクが保持されないことがあります。保存したPDFを実際に開き、リンクへカーソルを重ねてクリックできるか確認します。印刷した紙ではリンクをクリックできないため、必要なURLは短縮せず本文や脚注にも示す、QRコードを併記するなど用途に合わせます。

ページ内リンクは、PDF内の移動先へ変換されない場合があります。長いPDFでは自動生成した目次リンクも含めて確認してください。

セキュリティ設定でブロックされる場合

PDF閲覧ソフトやブラウザは、安全のため外部リンク、ローカルファイル、独自プロトコルを警告またはブロックすることがあります。javascript:のような危険なURLは使用せず、通常のhttps:リンクを使います。

社内URL、VPN内のページ、ログインが必要なリンクは、作成者には開けても閲覧者には開けません。シークレットウィンドウや権限の異なるアカウントでテストします。

配布前のリンク確認

症状別に最初の確認箇所を決める

まずリンク記法だけを残した短いMarkdownで試します。短い文書でも失敗するなら記法やURLが原因です。元の文書でだけ失敗するなら、括弧を含むURL、周囲のHTML、同名見出しなど、その文書固有の条件を確認します。

リンク名もSEOとアクセシビリティに影響する

「こちら」「詳細」のようなリンク名だけでは、前後を読まないと移動先が分かりません。「Markdown PDFの改ページを確認する」のようにリンク先の内容を簡潔に書くと、読み手、スクリーンリーダー、検索エンジンのいずれにも関係が伝わります。同じリンク名を別の移動先へ使い回さないことも重要です。

• すべての外部リンクがhttps://から始まっている
• リンク先を直接開いて404にならない
• 相対リンクと同じフォルダ構成を配布する
• ローカル絶対パスを使っていない
• 見出し変更後にページ内リンクを更新した
• 保存したHTMLとPDFの両方でクリックした
• 閲覧者の権限でもリンク先を開ける

変換前のプレビューだけで終わらせず、実際に配布するファイルを別の環境で開くことが、リンク切れを防ぐ最後の確認になります。

長く使う文書のリンク管理

手順書や仕様書を継続更新する場合は、外部リンクの確認日を記録し、定期的にリンク切れを確認します。同じURLを何度も使う文書では参照形式のリンクにまとめると、変更箇所を減らせます。

[製品サイト][product]
[操作ガイド][guide]

[product]: https://example.com/
[guide]: https://example.com/guide/

参照形式への対応も処理系によって異なるため、最終的なHTMLとPDFで確認します。リンク先の内容が変わる可能性も考え、重要な結論を外部ページだけに依存させないことが大切です。

よくある質問（FAQ）

Q. URLの末尾に句読点や閉じ括弧まで含まれてしまいます

文中のURLを自動でリンク化する処理では、直後の句読点や閉じ括弧まで移動先の一部と解釈されることがあります。自動検出に頼らず、[表示名](URL)のリンク記法で余分な文字を含まないURLを指定してください。コピー元から見えない改行が混ざっていないかも確認します。

Q. 印刷した紙の資料ではリンクをどう扱えばよいですか

紙ではクリックによる移動ができません。印刷を前提とする資料では、重要なリンク先のURLを短縮せず本文や脚注に読める形で示すか、QRコードを併記します。リンク名は「こちら」ではなく、リンク先の内容が分かる表記のままにしておくと紙面でも意味が通ります。

Q. 見出しを編集したらページ内リンクが動かなくなりました

見出し名を変更すると、そこから生成される見出しIDも変わるためです。同名の見出しに連番が付く処理系もあります。変換後のHTMLで実際の見出しIDを確認し、リンク側を更新してください。長い文書では自動生成の目次を使うと、手動でのリンク管理を減らせます。

Q. リンクを新しいタブで開かせることはできますか

標準のMarkdownには、新しいタブで開かせる共通の記法はありません。公開先のプラットフォームに明確な方針がない限り、開き方はブラウザや閲覧者の操作に任せるのが無難です。PDF閲覧ソフトでは、Webへのリンクが外部のブラウザで開かれることもあります。