Instruction file imported from shigeyf/github-copilot-best-practices-ja (.github/instructions/markdown.instructions.md). Copyright stays with the author.

Markdown ベストプラクティス

Markdown コンテンツのルール・ガイドライン

以下の markdown コンテンツのルールはバリデーターで強制されます:

1. 見出し: コンテンツを構造化するために適切な見出しレベル（H2、H3 など）を使用する。H1 見出しはタイトルに基づいて生成されるため、使用しない。
2. リスト: リストには箇条書きまたは番号付きリストを使用する。適切なインデントと間隔を確保する。
3. コードブロック: コードスニペットにはフェンス付きコードブロックを使用する。シンタックスハイライトのために言語を指定する。
4. リンク: リンクには適切な markdown 構文を使用する。リンクが有効でアクセス可能であることを確認する。
5. 画像: 画像には適切な markdown 構文を使用する。アクセシビリティのため alt テキストを含める。
6. テーブル: 表形式データには markdown テーブルを使用する。適切なフォーマットと配置を確保する。
7. 行の長さ: 可読性のため行の長さを 400 文字以内に制限する。
8. 空白: セクションを区切り可読性を向上させるため、適切な空白を使用する。
9. フロントマター: ファイルの先頭に必須のメタデータフィールドを含む YAML フロントマターを含める。

フォーマットと構造

markdown コンテンツのフォーマットと構造について、以下のガイドラインに従う:

• 見出し: H2 には ##、H3 には ### を使用する。見出しは階層的に使用する。コンテンツに H4 が含まれる場合は再構成を推奨し、H5 の場合はより強く推奨する。
• リスト: 箇条書きには -、番号付きリストには 1. を使用する。ネストされたリストは 2 スペースでインデントする。
• コードブロック: フェンス付きコードブロックを作成するにはトリプルバッククォート（```）を使用する。シンタックスハイライトのため、開始バッククォートの後に言語を指定する（例: ```csharp）。
• リンク: リンクには [リンクテキスト]\(URL\) を使用する。リンクテキストが説明的で URL が有効であることを確認する。
• 画像: 画像には ![alt テキスト](画像 URL) を使用する。alt テキストに画像の簡単な説明を含める。
• テーブル: テーブルを作成するには | を使用する。列が適切に配置され、ヘッダーが含まれていることを確認する。
• 行の長さ: 可読性を向上させるため 80 文字で改行する。長い段落にはソフト改行を使用する。
• 空白: セクションを区切り可読性を向上させるため空行を使用する。過度な空白は避ける。

バリデーション要件

以下のバリデーション要件への準拠を確保する:

• フロントマター: YAML フロントマターに以下のフィールドを含める:

  • post_title: 投稿のタイトル
  • author1: 投稿の主著者
  • post_slug: 投稿の URL スラッグ
  • microsoft_alias: 著者の Microsoft エイリアス
  • featured_image: フィーチャー画像の URL
  • categories: 投稿のカテゴリ。これらのカテゴリは /categories.txt のリストから選択する必要がある
  • tags: 投稿のタグ
  • ai_note: 投稿の作成に AI が使用されたかどうかを示す
  • summary: 投稿の簡潔な要約。可能な場合、コンテンツに基づいた要約を推奨する
  • post_date: 投稿の公開日

• コンテンツルール: コンテンツが上記で指定された markdown コンテンツルールに従っていることを確認する。

• フォーマット: コンテンツがガイドラインに従って適切にフォーマットおよび構造化されていることを確認する。

• バリデーション: ルールとガイドラインへの準拠を確認するためにバリデーションツールを実行する。