Markdown スタイルガイド

この記事は、ブログの長期的なスタイルガイドです。Markdown をゼロから解説するものではなく、一般的な執筆パターンが、コンテンツパイプライン、組版ルール、シンタックスハイライト、Mermaid レンダリング、脚注処理を経たあとの実際の見え方を示すためのものです。

テーマを調整するたびに、このページは視覚的なリグレッションをすばやく発見するのに役立つはずです。

段落と読みのリズム

構文

段落はテキストのまとまりであり、段落と段落の間は空行で区切ります。

2番目の段落は空行の後に始まります。同じ段組幅、行高、段落間隔を維持します。

効果

段落はテキストのまとまりであり、段落と段落の間は空行で区切ります。長文の組版では、快適な読み幅、十分な行高、安定した段落間隔を保つべきです。記事のカラムは、スマートフォン、タブレット、デスクトップ画面のいずれでも読みやすい状態を維持する必要があります。

2番目の段落は空行の後に始まります。前の段落と関連しつつ、近づきすぎないようにする必要があります。細かい間隔の問題は、しばしばここで顕在化します。

見出し

構文

## 章見出し

### 節見出し

#### 項目見出し

効果

節見出し

節見出しは、焦点を絞ったテーマを示すために使います。スキャンしやすく見つけられる一方で、本文を圧倒しないようにする必要があります。

項目見出し

項目見出しは、より大きな章の内部で、短い説明、例、部分的な構造を示すのに適しています。

インライン書式

インライン書式は強調や技術的な詳細に適しています：太字テキスト、強調テキスト、インラインコード、削除テキスト、そして 通常のリンク。多言語の混在も自然にできます：English text は中文、そして日本語と同じ行に置いても、読みのリズムを壊しません。

テクニカルライティングでは、いくつかのインライン HTML も役立ちます：H₂O、x²、i18n、⌘ + K、そして ハイライトテキスト。

引用ブロック

構文

> 優れた組版は構造を可視化しますが、ページを煩雑にはしません。
>
> 引用には **強調**、リンク、複数の段落を含めることもできます。

効果

優れた組版は構造を可視化しますが、ページを煩雑にはしません。

引用には 強調、リンク、複数の段落を含めることもできます。優れた引用スタイルは、本文と明確に区別でき、それでいて記事全体のビジュアルシステムの一部であるべきです。

引用の後の段落は、通常の本文のリズムにきれいに戻るべきです。

リスト

順序なしリストは、機能の概要を示すのに適しています：

• 組版は安定した間隔を保つべきです。
• リンクは明確に見えて、アクセスしやすいものであるべきです。
• 長いリスト項目は自然に折り返し、記事のカラムからはみ出さないようにする必要があります。

順序付きリストは、手順を示すのに適しています：

1. 下書きを書きます。
2. 記事をプレビューします。
3. 狭い画面と広い画面を確認します。
4. 書式が正しいことを確認して公開します。

ネストしたリストはスキャンしやすく保つべきです：

• コンテンツの確認
  • 見出し
  • 段落
  • リンク
• メディアの確認
  • 画像
  • Mermaid ダイアグラム
  • コードブロック

タスクリストは、互換性チェックに適しています：

• 段落
• リスト
• テーブル
• 脚注
• 印刷スタイル

テーブル

テーブルはコンパクトで読みやすく、狭い画面でも安全に表示されるべきです。

コードブロック

言語タグ付きのフェンスコードブロックを使用すると、シンタックスハイライトが正しい文法を選択できます。

type BlogPost = {
  title: string;
  description: string;
  tags: string[];
};

function summarizePost(post: BlogPost) {
  return `${post.title} — ${post.description}`;
}

コマンドラインコードも明確に表示されるべきです：

pnpm install
pnpm dev
pnpm build

フェンスコードブロック自体を含む Markdown ソースを表示する場合は、外側でより長いフェンスを使います：

```ts
console.log("Nested fence example");
```

画像

画像は記事の幅に従い、元のアスペクト比を維持し、意味のある代替テキストを提供する必要があります。

図表

Mermaid ダイアグラムは SVG としてレンダリングされ、Markdown 内ではソースのダイアグラムテキストが保持されるべきです。ダイアグラムはインラインで拡大縮小でき、はみ出す場合はドラッグでき、展開ボタンで開いて表示できます。

flowchart TD
A[マークダウンを書く] --> B[コンテンツを構築]
B --> C[記事をレンダリング]
C --> D[ブラウザで読む]
D --> E[リグレッションを発見]

区切り線

水平の区切り線は、関連しているが異なるコンテンツブロックを分けることができます。

区切り線の後の間隔は、意図を持って見えるべきであり、突然途切れる感じを与えるべきではありません。

脚注

脚注は、本文を中断させたくない小さな補足を置くのに適しています。この文には、レンダリングの流れを確認するための短い脚注が含まれています。¹

別の文でも2番目の脚注を使用して、より詳しい説明を記事の下部に置くことができます。²

まとめ

優れたサンプル記事は、十分に多くのトピックに対応できるものでありながら、読みやすいものであるべきです。将来のスタイル変更が見出し、リスト、引用、コードブロック、図表、脚注に影響を与えた場合、このページは問題を明確にしてくれるはずです。