Markdown のベストプラクティス

2025-05-06

この記事では、ドキュメントで Markdown を使用するための具体的なガイダンスを示します。 Markdown のチュートリアルではありません。 Markdown のチュートリアルが必要な場合は、この Markdown のチートシートを参照してください。

ドキュメントをビルドするビルドパイプラインでは、 Markdig を使用して Markdown ドキュメントを処理します。 Markdig は、最新の CommonMark 仕様の規則に基づいてドキュメントを解析します。 OPS は CommonMark 仕様に従い、テーブルやアラートなど、プラットフォーム固有の機能の拡張機能をいくつか追加します。

CommonMark 仕様は、一部の Markdown 要素の構築に関してより厳密です。このドキュメントに記載されている詳細に細心の注意を払います。

VS Code では markdownlint 拡張機能を使用して、スタイルと書式設定の規則を適用します。この拡張機能は、 Learn Authoring Pack の一部としてインストールされます。

空白行、スペース、タブ

空白行は Markdown のブロックの終わりを示します。

異なる型の Markdown ブロックの間に 1 つの空白を配置します。たとえば、段落とリストまたはヘッダーの間などです。
複数の空白行を使用しないでください。複数の空白行が HTML で 1 つの空白行としてレンダリングされるため、余分な空白行は不要です。
コードブロックに複数の連続する空白行を配置しないでください。連続する空白行はコードブロックを中断します。

マークダウンでは間隔が重要です。

行の末尾に余分なスペースを削除します。末尾のスペースは、Markdown のレンダリング方法を変更できます。
常にタブ (ハードタブ) の代わりにスペースを使用します。

タイトルと見出し

ATX 見出しのみを使用します (#または=スタイルヘッダーではなく、- スタイル)。

文章ケースを使用します - 固有名詞とタイトルまたはヘッダーの最初の文字のみを大文字にします。
#と見出しの最初の文字の間に 1 つのスペースを含める
見出しを 1 行の空白行で囲む
ドキュメントごとに複数の H1 を使用しない
- 最初のヘッダーにする必要があります
- これは、記事のタイトルと一致する必要があります
ヘッダーレベルを 1 ずつインクリメントする - レベルをスキップしない
深度を H3 または H4 に制限する
ヘッダーで太字やその他のマークアップを使用しないようにする

行の長さを 100 文字に制限する

概念記事とコマンドレットリファレンスの場合は、行を 100 文字に制限します。 about_アーティクルの場合は、行の長さを 79 文字に制限します。行の長さを制限すると、 git の差分と履歴の読みやすさが向上します。また、他のライターが投稿を行うのも簡単になります。

VS Code で Reflow Markdown 拡張機能を使用して、指定された行長に合わせて段落をリフローします。

一部のコンテンツタイプは簡単にリフローできません。たとえば、コードブロック内のコードは、コンテンツとコード言語によっては、リフローが困難な場合もあります。テーブルをリフローすることはできません。このような場合は、コンテンツを可能な限り 100 文字の制限に近づけるために、最善の判断を使用してください。

強調

強調するために、Markdown は太字と斜体をサポートしています。 Markdown を使用すると、 * または _ を使用して強調をマークできます。ただし、一貫性を保ち、意図を示すには、次の手順を実行します。

太字に ** を使用する
斜体に _ を使用する

このパターンに従うと、文書に太字と斜体が混在している場合に、マークアップの意図を他のユーザーが理解しやすくなります。

複数の文が含まれていない限り、リストアイテムをピリオドで終了しないでください。
アスタリスク (-) を使用する強調マークアップとの混同を避けるために、箇条書きにはハイフン文字 (*) を使用します。
段落またはその他の要素を箇条書き項目の下に含めるには、改行を挿入し、行頭文字の後の最初の文字にインデントを合わせます。

例えば次が挙げられます。

This is a list that contains child elements under a bullet item.

- First bullet item

  Sentence explaining the first bullet.

  - Child bullet item

    Sentence explaining the child bullet.

- Second bullet item
- Third bullet item

これは、箇条書き項目の下に子要素を含むリストです。

最初の箇条書き項目

最初の箇条書きの内容文。
- 子の箇条書き項目
  
  子の箇条書きの内容文。
2 番目の箇条書き項目
3 番目の箇条書き項目

順序指定されたリスト

番号付きリスト内のすべての項目は、各項目をインクリメントするのではなく、 1. 番号を使用する必要があります。
- Markdown レンダリングでは、値が自動的にインクリメントされます。
- これにより、アイテムの並べ替えが容易になり、下位コンテンツのインデントが標準化されます。
段落またはその他の要素を番号付き項目の下に含めるには、インデントを項目番号の後の最初の文字に合わせます。

例えば次が挙げられます。

1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to
   the next line and must line up with the first character after the numbered list marker.

   To include a second element, insert a line break after the first and align indentations. The
   indentation of the second element must line up with the first character after the numbered list
   marker.

1. The next numbered item starts here.

結果の Markdown は次のようにレンダリングされます。

最初の要素の場合は、 1の後に 1 つのスペースを挿入します。長い文は次の行に折り返す必要があり、番号付きリストマーカーの後の最初の文字と一緒に並ぶ必要があります。

2 番目の要素を含めるには、最初の要素の後に改行を挿入し、インデントを揃えます。 2 番目の要素のインデントは、番号付きリストマーカーの後の最初の文字に合わせて配置する必要があります。
次の番号付き項目はここから始まります。

画像

イメージを含める構文は次のとおりです。

![[alt text]](<folderPath>)

Example:
![Introduction](./media/overview/Introduction.png)

ここで、 alt text はイメージの簡単な説明であり、 <folderPath> はイメージへの相対パスです。

視覚障害者のスクリーンリーダーをサポートするには、代替テキストが必要です。
画像は、アーティクルを含むフォルダー内の media/<article-name> フォルダーに格納する必要があります。
- media フォルダーの下に、記事のファイル名と一致するフォルダーを作成します。その記事の画像をその新しいフォルダーにコピーします。
記事間で画像を共有しないでください。
- 1 つのイメージが複数のアーティクルで使用されている場合は、各フォルダーにそのイメージのコピーが必要です。
- これにより、ある記事の画像に対する変更が別のアーティクルに影響を与えるのを防ぐことができます。

次のイメージファイルの種類がサポートされています: *.png、 *.gif、 *.jpeg、 *.jpg、 *.svg

Markdown 拡張機能 - アラートボックス

Learn Authoring Pack には、発行システム固有の機能をサポートするツールが含まれています。アラートは、コンテンツの重要性を強調する色とアイコンでレンダリングするブロッククォートを作成するための Markdown 拡張機能です。次のアラートの種類がサポートされています。

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

Microsoft Learn では、次のようなアラートが表示されます。

メモ帳

注

スキミングを行ってもユーザーが気付く必要がある情報。

ヒントブロック

ヒント

ユーザーの成功に役立つオプションの情報。

重要なブロック

重要

ユーザーの成功に必要な重要な情報。

注意事項ブロック

注意事項

アクションの潜在的な悪影響。

警告ブロック

警告

アクションの危険な特定の結果。

Markdown 拡張機能 - テーブル

テーブルは、次で構成される行と列を含むデータの配置です。

1 つの見出し行
ヘッダーをデータから分離する区切り記号行
ゼロ以上のデータ行

各行は、パイプ (|) で区切られた任意のテキストを含むセルで構成されます。わかりやすくするために、先頭と末尾のパイプも推奨されます。パイプとセルの内容の間のスペースがトリミングされます。ブロックレベルの要素をテーブルに挿入することはできません。行のすべてのコンテンツは、1 行に存在する必要があります。

区切り記号行は、コンテンツがハイフン (-) のみのセルで構成され、必要に応じて、先頭または末尾のコロン (:)、またはその両方で構成され、それぞれ左、右、または中央の配置を示します。

小さいテーブルの場合は、代わりにリストを使用することを検討してください。リストは次のとおりです。

保守と読み取りが容易
100 文字の行制限内に収まるようにリフローできます
スクリーンリーダーを使用して視覚的支援を行うユーザーがアクセスしやすくする

詳細については、Microsoft Learn の Markdown リファレンスの「テーブル」セクションを参照してください。

ハイパーリンク

ハイパーリンクには Markdown 構文 [friendlyname](url-or-path)を使用する必要があります。
発行システムでは、次の 3 種類のリンクがサポートされています。
- URL リンク
- ファイルリンク
- 相互参照リンク
外部 Web サイトに対するすべての URL は、ターゲットサイトに対して有効でない場合を除き、HTTPS を使用する必要があります。
リンクにはフレンドリ名が必要です。通常はリンクされた記事のタイトルです。
ハイパーリンクの角かっこ内でバックティック、太字、またはその他のマークアップを使用しないでください。

ベア URL は、特定の URI を文書化するときに使用できますが、バックティックで囲む必要があります。例えば次が挙げられます。

By default, if you don't specify this parameter, the DMTF standard resource URI
`http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.

リンク参照は許可されている場合に使用します。段落内のリンク参照により、段落の読みやすさが高くなります。

リンク参照は、Markdown リンクを 2 つの部分に分割します。
- リンク参照 - [friendlyname][id]
- リンク定義 - [id]: url-or-path

URL 型のリンク

learn.microsoft.comに関する他の記事への URL リンクでは、サイト相対パスを使用する必要があります。サイト相対リンクを作成する最も簡単な方法は、ブラウザーから URL をコピーし、マークダウンに貼り付ける値から https://learn.microsoft.com/en-us を削除することです。
Microsoft のプロパティの URL (URL から /en-us を削除する) または Wikipedia のリンクにロケールを含めないでください。
不要なクエリパラメーターを URL から削除します。削除する必要がある例:
- ?view=powershell-5.1 - PowerShell の特定のバージョンへのリンクに使用されます
- ?redirectedfrom=MSDN - 古い記事から新しい場所にリダイレクトされたときに URL に追加されました
ドキュメントの特定のバージョンにリンクする必要がある場合は、クエリ文字列に &preserve-view=true パラメーターを追加する必要があります。例: ?view=powershell-5.1&preserve-view=true
Microsoft サイトでは、URL リンクにはファイル拡張子が含まれません (たとえば、 .mdなし)

ファイルの種類のリンク

ファイルリンクは、ある参照記事から別の参照記事、または同じドキュメントセット内のある概念記事から別の記事にリンクするために使用されます。
- 概念記事から参照記事にリンクする必要がある場合は、URL リンクを使用する必要があります。
- 別のドキュメントセットまたはリポジトリ間の記事にリンクする必要がある場合は、URL リンクを使用する必要があります。
相対ファイルパスを使用する (例: ../folder/file.md)
すべてのファイルパスでフォワードスラッシュ (/) 文字が使用されます
ファイル拡張子を含める (例: .md)

相互参照リンク

相互参照リンクは、発行システムでサポートされる特別な機能です。概念記事のクロスリファレンスリンクを使用して、.NET API またはコマンドレットリファレンスにリンクできます。

.NET API リファレンスへのリンクについては、中央の寄稿者ガイド内のセクションドキュメントでリンクを使うを参照してください。
コマンドレット参照へのリンクの形式は次のとおりです: xref:<module-name>.<cmdlet-name>。たとえば、Get-Content モジュールのコマンドレットにリンクします。

[Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)

ディープリンク（深いリンク）

ディープリンクは、URL とファイルリンクの両方で許可されます。

アンカーテキストは小文字にする必要があります
ターゲットパスの末尾にアンカーを追加します。例えば：
- [about_Splatting](about_Splatting.md#splatting-with-arrays)
- [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

詳細については、ドキュメントのリンクを使用するを参照してください。

コードスパン

コードスパンは、段落内のインラインコードスニペットに使用されます。単一のバッククォートを使用して、コードスパンを示します。例えば次が挙げられます。

PowerShell cmdlet names use the `Verb-Noun` naming convention.

この例では、次のようにレンダリングされます。

PowerShell コマンドレット名には、 Verb-Noun 名前付け規則が使用されます。

コードブロック

コードブロックは、コマンド例、複数行コードサンプル、クエリ言語、出力に使用されます。アーティクルファイル内のテキストのセクションをコードブロックとして示すには、トリプルバックティック (```) で囲む方法とインデントする方法の 2 つの方法があります。

インデントを使用しないでください。誤りが発生するのは簡単すぎるため、別のライターが記事を編集する必要があるときに意図を理解するのが難しい場合があります。

フェンスされたコードブロックには、ブロックに含まれる言語構文を示す省略可能なタグを含めることができます。発行プラットフォームでは、言語タグの一覧がサポートされています。言語タグは、記事が Web ページに表示されるときに構文を強調表示するために使用されます。言語タグでは大文字と小文字は区別されませんが、いくつかの特殊なケースを除き、小文字を使用する必要があります。

タグのないコードフェンスは、構文ブロックや、構文の強調表示が不要な他の種類のコンテンツに使用できます。
コマンドからの出力を表示する場合は、タグ付けされたコードフェンスと言語タグ Outputを使用します。レンダリングされたボックスには出力というラベルが付き、構文が強調表示されていません。
出力がサポートされている特定の言語にある場合は、適切な言語タグを使用します。たとえば、多くのコマンドで JSON が出力されるため、 json タグを使用します。
サポートされていない言語タグを使用すると、コードブロックは構文の強調表示なしでレンダリングされます。言語タグは、Web ページに表示されるコードボックスのラベルになります。ラベルが Web ページで大文字になるように、タグを大文字にします。

次のステップ

PowerShell スタイルガイドの

次の方法で共有

Markdown のベスト プラクティス