この記事は、このブログのための継続的なスタイルガイドです。Markdown を一から説明するためではなく、よく使う書き方がコンテンツ処理、タイポグラフィ、シンタックスハイライト、Mermaid レンダリング、脚注処理を通ったあとにどう見えるかを確認するためにあります。
テーマを変更したとき、このページで視覚的な崩れを見つけやすくなるはずです。
段落と読みやすさ
構文
段落は、空行で区切られたテキストのまとまりです。
二つ目の段落は空行の後に始まり、同じ行幅、行間、余白を保つ必要があります。表示
段落は、空行で区切られたテキストのまとまりです。長文では、読みやすい行幅、十分な行間、安定した段落間の余白が必要です。記事カラムはスマートフォン、タブレット、デスクトップのどれでも読みやすくあるべきです。
二つ目の段落は空行の後に始まります。前の段落とつながって見えつつ、近すぎないことが大切です。小さな余白の問題は、このような場所で見つかりやすくなります。
見出し
構文
## セクション見出し
### サブセクション見出し
#### 詳細見出し表示
サブセクション見出し
サブセクション見出しは、ひとつの focused な内容を導入します。本文より目立ちすぎず、読み飛ばし中にも見つけやすい必要があります。
詳細見出し
詳細見出しは、大きなセクションの中で短い補足、例、局所的な構造を作るときに便利です。
インライン書式
インライン書式は強調や小さな技術的詳細に向いています：太字、強調、インラインコード、削除テキスト、そして 通常のリンク。複数言語の混在も自然に見える必要があります。English text と中文、そして日本語が同じ行にあっても、行のリズムが崩れないことが大切です。
技術記事ではインライン HTML も役立ちます：H2O、x2、i18n、⌘ + K、そして ハイライトされたテキスト。
引用
構文
> 良いタイポグラフィは、ページを忙しくせずに構造を見せます。
>
> 引用には **強調**、リンク、複数の段落を入れられます。表示
良いタイポグラフィは、ページを忙しくせずに構造を見せます。
引用には 強調、リンク、複数の段落を入れられます。良い引用スタイルは本文と区別でき、同時に記事全体の中になじむ必要があります。
引用の後の段落は、自然に通常の本文リズムへ戻る必要があります。
リスト
箇条書きは機能の要約に便利です：
- タイポグラフィは安定した余白を保つ。
- リンクは見やすく、アクセスしやすい。
- 長いリスト項目は自然に折り返され、記事カラムの外にはみ出さない。
番号付きリストは手順に向いています：
- 下書きを書く。
- 記事をプレビューする。
- 狭い画面と広い画面を確認する。
- 表示を確認して公開する。
ネストしたリストも読み取りやすくあるべきです：
- コンテンツ確認
- 見出し
- 段落
- リンク
- メディア確認
- 画像
- Mermaid 図表
- コードブロック
タスクリストは互換性チェックに便利です：
- 段落
- リスト
- 表
- 脚注
- 印刷スタイル
表
表はコンパクトで読みやすく、狭い画面でも安全に表示される必要があります。
| 機能 | Markdown 構文 | 期待される表示 |
|---|---|---|
| 太字 | **bold** | 強調表示 |
| インラインコード | `const value = 1` | 等幅のインライン文字 |
| リンク | [Astro](https://astro.build) | アクセス可能なリンク |
| 脚注 | [^note] | リンク付き注記番号 |
コードブロック
言語ラベル付きの fenced code block を使うと、シンタックスハイライトが正しい文法を選べます。
type BlogPost = {
title: string;
description: string;
tags: string[];
};
function summarizePost(post: BlogPost) {
return `${post.title} — ${post.description}`;
}シェルコマンドも読みやすく表示される必要があります：
pnpm install
pnpm dev
pnpm buildMarkdown の中に fenced code block を含めた例を表示したいときは、外側により長いフェンスを使います：
```ts
console.log("Nested fence example");
```画像
画像は記事の幅に収まり、元の比率を保ち、意味のある代替テキストを持つ必要があります。
図表
Mermaid 図表は SVG として表示され、Markdown には元の図表テキストが残ります。図表はインラインで拡大縮小でき、はみ出したときはドラッグでき、展開ボタンから大きく表示できます。
flowchart LR
A[Markdown を書く] --> B[コンテンツをビルド]
B --> C[記事をレンダリング]
C --> D[ブラウザで読む]
D --> E[崩れを見つける]水平線
水平線は、関連しているが別の内容を分けるときに使えます。
水平線の後の余白は、唐突ではなく意図的に見える必要があります。
脚注
脚注は、本文の流れを止めずに小さな補足を入れたいときに便利です。この文にはレンダリング処理を確認するための短い脚注があります。1
もう一つの文にも二つ目の脚注を付けて、細かな説明を記事の下部に送れます。2
まとめ
良いサンプル記事は、テーマの機能を広く確認できる一方で、読み物としても不自然でない必要があります。将来のスタイル変更で見出し、リスト、引用、コードブロック、図表、脚注が崩れた場合、このページで問題に気づけるはずです。