Markdown: マークダウンリンク構文と参照リンク
リンクはインターネットのバックボーンです。Markdown では、単一の構文でドキュメントを全世界に接続します。
1. 学ぶこと
- インラインリンクと参照リンクの構文
- GitHub プロジェクトでの相対リンクの使用
- 自動リンクと電子メールリンク
- アンカーリンクを使用したドキュメント内での移動
- ベスト プラクティスと SEO の最適化をリンクする
2. ドキュメンテーション エンジニアの実話
(1) 問題点: リンク切れによりユーザーが迷子になる
Emma は、SaaS 会社のドキュメント エンジニアです。彼女は、ヘルプ ドキュメント内のリンクの約 15% が壊れていることを発見しました。その一部はファイル名が変更されたためであり、その他は外部サイトが移行したためです。ユーザーは「リンクをクリックすると 404 ページが表示される」と報告しました。さらに悪いことに、一部のリンクが数十の Markdown ファイルに分散されており、修正するのに数日かかりました。
(2) 解決策: 相対リンクと参照リンクを使用する
Emma はリンク標準を確立しました。すべての内部リンクは相対パス (ドメインに依存しない) を使用し、頻繁に使用されるリンクは各ドキュメントの下部にある参照セクションで定義されます (1 つの変更はどこにでも適用されます)。彼女はまた、すべてのリンクの有効性を定期的にスキャンするスクリプトも作成しました。 3 か月後、リンク切断率は 15% から 0.5% に低下しました。
3. インラインリンク
インライン リンクは、Markdown で最も一般的なリンク形式であり、直感的な構文を備えています。
MARKDOWN
[Display Text](URL)
[Visit GitHub](https://github.com)
| パート | 説明 | 例 |
|---|---|---|
[Display Text] |
ユーザーに表示されるクリック可能なテキスト | [Visit Website] |
(URL) |
ターゲット URL | (https://example.com) |
(1) タイトル属性の追加
URL (ホバー上に表示) の後に、オプションの title 属性を追加できます。
MARKDOWN
[Google](https://google.com "Visit Google Search")
[MDN Docs](https://developer.mozilla.org "Comprehensive Web Technology Documentation")
💡 ヒント: title 属性は SEO に多少役立ちますが、より重要なのは、スクリーン リーダーがタイトルの内容を読み上げるため、アクセシビリティが向上することです。
▶ 例: さまざまな種類の外部リンク
MARKDOWN
- [Google](https://google.com) — Search engine
- [GitHub](https://github.com "The world's largest code hosting platform") — Code hosting
- [MDN Web Docs](https://developer.mozilla.org) — Web technology documentation
(1) 参照リンクを定義する 3 つの方法
MARKDOWN
Method 1 (most common, with brackets):
[google]: https://google.com
Method 2 (shorthand without brackets):
Google: https://google.com
Method 3 (implicit link ID, auto-matches):
[Google][]
...
[Google]: https://google.com
💡 ヒント:
[Google][] のような暗黙的なリンクは、括弧テキストを ID として自動的に使用し、[Google]: 定義を検索します。リンクテキストとIDが同じ場合に便利です。
▶ 例: 完全な参照リンクの使用法
MARKDOWN
## Recommended Resources
For web development, check out [MDN][] and [W3Schools][].
For code hosting, try [GitHub][]; for Q&A, visit [Stack Overflow][].
## References
- [MDN][]'s CSS documentation is comprehensive
- [Stack Overflow][] has tons of frontend Q&A
[MDN]: https://developer.mozilla.org/en-US/
[W3Schools]: https://www.w3schools.com/
[GitHub]: https://github.com
[Stack Overflow]: https://stackoverflow.com/
💡 ヒント: 参照リンクの最大の利点は保守性です。外部リンクが変更された場合、下部の 1 行を変更するだけで、すべての参照が自動的に更新されます。
5. 相対リンク
GitHub プロジェクトまたはローカル ドキュメントでは、相対パスを使用して同じプロジェクト内の他のファイルにリンクします。
TEXT
📖 参照専用
Project Documentation:
Installation Guide → installation.md
API Reference → api/overview.md
FAQ → faq.md
Previous Section → chapter-1/intro.md
⚠️ 注: 相対パスはドメインに依存しません。 GitHub では、同じリポジトリ内の他のファイルを指すリンクは、絶対 URL ではなく相対パスを使用する必要があります。これにより、リンクはクローン作成またはフォーク後も有効なままになります。
▶ 例: GitHub プロジェクトのリンク構造
TEXT
📖 参照専用
Awesome Project
Quick Start: See docs/installation.md
Contribution Guide: Check CONTRIBUTING.md
Related Projects: Core Library (packages/core/README.md)
CLI Tool (packages/cli/README.md)
6. 自動リンクと電子メールリンク
(1) 自動リンク
URL または電子メール アドレスを <> で囲むと、Markdown が自動的にリンクを生成します。
MARKDOWN
<https://example.com>
<user@example.com>
(2) 自動リンクの無効化
場合によっては、URL をクリック可能にせずに表示したい場合は、コードの書式設定またはエスケープを使用します。
MARKDOWN
`https://example.com` (displayed as code, not clickable)
Or:
\*\*https://example.com\*\* displays the URL as plain text
▶ 例: 自動リンクとプレーンテキスト URL
MARKDOWN
Auto link: <https://www.google.com>
Plain text (no auto-link): https://www.google.com
Link with text: [Visit Google](https://www.google.com)
💡 ヒント: ほとんどのパーサーは、
http:// または https:// で始まる URL を自動検出し、<> がなくてもリンクを生成します。しかし、標準の Markdown では、<> を使用するのが明示的なアプローチです。
7. アンカー リンク (ページ内ナビゲーション)
アンカー リンクを使用すると、ユーザーはクリックして同じページ上の特定の場所にジャンプできます。
MARKDOWN
## Table of Contents
- [Introduction](#1-introduction)
- [Installation](#2-installation)
- [Configuration](#3-configuration)
---
## 1. Introduction
...
Jump to [Back to Top](#table-of-contents)
⚠️ 注: GitHub は見出しをアンカー ID に自動変換します。中国語の文字はピンインまたは Unicode になります。英語はハイフンを入れると小文字になります。レンダリングされたページ URL の
# 部分をチェックして、実際のアンカー値を確認します。
▶ 例: アンカー リンクを含む目次
MARKDOWN
# Python Tutorial
## Table of Contents
- [Installing Python](#1-installing-python)
- [First Program](#2-first-program)
- [FAQ](#faq)
---
## 1. Installing Python
...
## 2. First Program
...
## ❓ よくある質問
...
8. 完全な例: ドキュメント リンク ネットワーク
MARKDOWN
# Web Development Learning Path
## Frontend Basics
| Technology | Documentation | Description |
|:-----|:-----|:-----|
| HTML | [MDN HTML][mdn-html] | Web structure |
| CSS | [MDN CSS][mdn-css] | Web styling |
| JS | [MDN JS][mdn-js] | Interactivity |
## Hands-On Projects
Refer to the [Project Template][repo] to start your first website.
## Related Content
- Check [Internal Notes](notes/frontend-roadmap)
- Join the [Community Forum][forum]
- Contact: <author@example.com>
[mdn-html]: https://developer.mozilla.org/en-US/docs/Web/HTML
[mdn-css]: https://developer.mozilla.org/en-US/docs/Web/CSS
[mdn-js]: https://developer.mozilla.org/en-US/docs/Web/JavaScript
[repo]: https://github.com/example/web-starter
[forum]: https://community.example.com
期待される結果: インライン リンク、参照リンク、表リンク、電子メール リンクを組み合わせて完全な学習リソース ネットワークを構築する、よく構造化されたドキュメント ページ。
❓ よくある質問
Q インライン リンクと参照リンクのどちらを選択すればよいですか?
A リンクが 1 回だけ表示される場合は、インライン リンクを使用します。同じリンクが複数回表示される場合、または一元的なメンテナンスが必要な場合は、参照リンクを使用します。
Q リンクを新しいタブで開くにはどうすればよいですか?
A 標準のマークダウンは
target="_blank" をサポートしていません。 HTML を使用する必要があります: <a href="url" target="_blank">Text</a>。Q 画像にリンクを含めることはできますか?
A はい。ネストされた構文
[](link url) を使用して、画像をクリックすると URL に移動します。Q リンクのタイトル属性は SEO にとって重要ですか?
A 影響は最小限ですが、タイトル属性はアクセシビリティを向上させます。本当の SEO の鍵は、リンク テキスト自体を説明的なものにすることです。「ここをクリック」の代わりに「インストール ガイドを表示」を使用してください。
📖 まとめ
- インライン リンク:
[text](url)、最も一般的で直感的 - 参考リンク:
[text][id]+[id]: url、一元管理 - 相対リンク: 同じプロジェクト内で相対パスを使用し、移行しやすいようにします。
- 自動リンク:
<url>または<email>はクリック可能なリンクを自動生成します - アンカー リンク:
#headingページ上の特定の場所にジャンプします - アクセシビリティと SEO を向上させるために、リンク テキストを説明的なものにしてください
📝 練習問題
-
基本: 少なくとも 3 つの外部参照を含むインライン リンクを使用して短い記事を作成します (例: よく使用する 3 つのオンライン ツールを推奨します)。
-
中級: 参照リンクを使用して上記の演習を書き直します。次に、短い GitHub プロジェクトを作成し、相対リンクを使用してユーザーを README.md から
docs/の下のサブページに誘導します。 -
課題: インライン リンク、参照リンク (少なくとも 5 つ)、目次ナビゲーション用のアンカー リンク、および下部の電子メール自動リンク
<user@example.com>を組み合わせた「学習リソース ハブ」ドキュメントを作成します。
