Markdown実践執筆ガイド：読みやすくクリーンな記事を書くためのルール

ドキュメント作成やブログ記事執筆において、**Markdown（マークダウン）**はシンプルかつ強力なツールです。しかし、複数人で開発・運用を続けたり、将来的な保守性を担保するためには、「ただ動くように書く」だけでなく、「読みやすく整ったルールで書く」ことが極めて重要になります。

本ガイドでは、本サイト（Astro製ポートフォリオ）における基本的なMarkdownの執筆ルールと、読みやすい記事作りのための実践的なベストプラクティスを解説します。

1. 見出し（Headings）の構造化

見出しは文章の「骨組み」です。検索エンジン（SEO）やスクリーンリーダー、読者が一目で構成を把握できるように、階層構造（親子関係）を正しく守って執筆します。

ルール

  • 見出し1（#）は原則として記事タイトル専用とし、本文内では見出し2（##）から開始します。
  • 見出しのレベルを飛ばさないでください（例：## の直後に #### を置かず、必ず ### を挟む）。
  • # と見出し文字列の間には、半角スペースを1つ空けます。

記述例

## 2. 現在の主な取り組み（h2）

### 2.1 医療システムにおける連携コーディネート（h3）

#### 連携システム例（h4）

2. 段落とテキスト装飾（強調・コード等）

読みやすさを追求するために、適切な装飾と言葉遣いを意識しましょう。

段落の区切り

Markdownでは、段落と段落の間は1行の空行を入れて区切ります。

強調表現

重要な単語や文章は、太字（**）または斜体（_）で装飾します。ただし、太字を多用しすぎると画面がうるさくなり可読性が下がるため、1段落につき1、2箇所に留めるのがベストです。

  • 太字: **強調したい文章**
  • 斜体: _斜体にする文章_

インラインコード

テキスト中で、プログラムの変数名、関数、ファイル名、コマンドなどを言及する場合は、バッククォート（`）で囲んでインラインコードとして表記します。

  • 例: 設定ファイルである .clauderules を編集します。

3. リストと箇条書き

複雑な情報や手順は、文章ではなくリスト形式に整理することで一気に読みやすくなります。

無番号リスト（箇条書き）

並列する項目を整理する場合に使用します。記号にはハイフン（-）を使用します。

- バックエンド: PHP (Laravel) / C#
- フロントエンド: JavaScript / TypeScript
- データベース: SQL Server / MySQL

番号付きリスト

手順や優先順位を明確に示したい場合に使用します。

1. Webフィルタ機能を一時的に無効化（OFF）する
2. 機器本体を再起動する
3. 再起動完了後、Webフィルタ機能を再度有効（ON）にする

4. 引用（Blockquotes）

外部ソースからの引用や補足情報、重要な注意喚起を明示する場合は、引用記号（>）を使用します。

記述例

> **注意点**: Webフィルタを一時的にOFFにする際は、セキュリティリスクを最小限に抑えるため、作業中のネットワーク制限や迅速な再起動対応を心がけてください。

注意点: Webフィルタを一時的にOFFにする際は、セキュリティリスクを最小限に抑えるため、作業中のネットワーク制限や迅速な再起動対応を心がけてください。

5. コードブロックとシンタックスハイライト

技術ブログ等でソースコードを提示する際は、トリプルバッククォート（```）を使用し、開始タグの直後にプログラミング言語名を記述してシンタックスハイライト（色分け）を有効にします。

記述例

​```javascript
function greet(name) {
    console.log(`Hello, ${name}!`);
}
greet("Share Lab");
​```

実際の出力

function greet(name) {
    console.log(`Hello, ${name}!`);
}
greet("Share Lab");

6. テーブル（表）

データの比較や、設定値の対応表などを簡潔にまとめるにはテーブル（表）が有効です。

記述例

| 技術領域 | 主な言語・フレームワーク | 経験・注力度 |
| :--- | :--- | :--- |
| バックエンド | PHP (Laravel), C# (MVC4) | 10年以上 / 得意 |
| フロントエンド | JavaScript, Astro | 近年注力中 |
| データベース | SQL Server, MySQL | 設計・最適化可能 |

実際の出力

技術領域 主な言語・フレームワーク 経験・注力度
バックエンド PHP (Laravel), C# (MVC4) 10年以上 / 得意
フロントエンド JavaScript, Astro 近年注力中
データベース SQL Server, MySQL 設計・最適化可能

7. 画像とリンク

リンクや画像を挿入する際は、以下の記法を使用します。Astroプロジェクト内では、画像パスの指定に注意が必要です。

リンクの記述例

詳細は [Share Lab の活動ブログ](https://note.com/share_lab) をご覧ください。

画像の記述例

![自己紹介用の画像](../../assets/blog-placeholder-about.jpg)

Astroで記事を書く際、画像は通常 src/assets/ に配置し、記事（src/content/blog/ 内）からは相対パス ../../assets/画像名 で参照します。これにより、ビルド時に自動的に画像が最適化されます。

8. まとめ：クリーンなMarkdownを保つために

読みやすくクリーンな記事を継続して作成するためには、以下の「メンテナンスのルール」を意識してみてください。

  1. if文同様、文章のネストを深くしない: 見出しの階層が深すぎると、読者が迷子になります。見出しは「h3（###）」までを目安に構成しましょう。
  2. 意味のある改行と空行: Markdownパーサーが正しく解釈できるよう、リストの前後や見出しの前には、必ず1行の空行を空けてください。
  3. 継続的な更新とドキュメントの鮮度: 情報は古くなるものです。定期的にドキュメントを見直し、最新の知見（AI活用、Cursor / MCPの活用法など）をアップデートしていくことで、サイト自体の価値を高めることができます。

ぜひこのガイドを参考に、読みやすく価値のあるコンテンツをどんどん増やしていってください！