Markdown の基本

MDB Markdown

Markdown（マークダウン）は、テキストに簡単な記号を足すだけで見出し・リスト・リンクなどが表現できる軽量な記法。.md の拡張子で保存する。

Claude Code に Webアプリの仕様を依頼するとき、ブログ記事を書くとき、GitHub の README を書くとき、Notion や Slack でメモを取るとき。あちこちで使われているので、書き方を一度押さえておくと応用範囲が広い。

本記事は記法の全体像を一通り確認するためのリファレンス。必要なときに該当章を辞書のように参照する想定。

1. Markdownとは

Markdown は2004年に John Gruber が考案したテキスト記法。「読みやすいまま装飾もできる」ことを目指している。プレーンテキストにそのまま # や * のような記号を混ぜて書くと、変換ツールで HTML に変換できる。

# 大きな見出し
これは本文。**強調** したり、[リンク](https://example.com) を貼ったりできる。

これを HTML にすると：

<h1>大きな見出し</h1>
<p>これは本文。<strong>強調</strong> したり、<a href="https://example.com">リンク</a> を貼ったりできる。</p>

変換は Astro・GitHub・Markdown プレビューツールなどがやってくれる。書き手はテキストエディタで .md を書くだけでよい。

なお、本サイト（vibecodingnotes.com）の記事もすべて Markdown で書かれている。.md ファイルをClaude Codeで作った小さな Python スクリプトで HTML に変換し、Cloudflare Pages で公開している。いま読んでいるこの記事も .md から変換されたもの。

Markdown には方言（CommonMark、GFM、Pandoc など）があり、表や脚注の扱いが少しずつ違う。本記事は GitHub Flavored Markdown（GFM）に近い、よく使われる範囲を扱う。

2. 見出し・段落・強調

2-1. 見出し

行頭に # を入れる。# の数が見出しレベル（1〜6）。

# 見出し1（記事タイトル）
## 見出し2（章）
### 見出し3（節）
#### 見出し4

ブログ記事や技術文書では、# は1ページに1つだけ（記事タイトル）、## 以下を内容の区切りに使うのが一般的。

2-2. 段落と改行

段落は空行で区切る。

これは1つ目の段落。

これは2つ目の段落。

行末に何も入れずに改行しても、HTMLでは改行と認識されない（連続する1つの段落として扱われる）。改行したいときは行末に半角スペース2つ（）を入れるか、<br> タグを使う。

2-3. 強調

**太字** または __太字__
*斜体* または _斜体_
~~取り消し線~~

** で囲むと太字、* で囲むと斜体、~~ で囲むと取り消し線。

本サイトでは太字を「UIラベル」（Save ボタン、ファイル メニューなど）にだけ使う運用にしている。文章中の単なる強調にはあまり使わない。

3. リスト

3-1. 順序なしリスト

-（または *、+）を行頭につける。

- りんご
- みかん
- バナナ

3-2. 順序付きリスト

数字 + . を行頭につける。番号は適当でよく、レンダリング時に振り直される。

1. 最初のステップ
2. 次のステップ
3. 最後のステップ

3-3. ネスト（入れ子）

行頭に2スペース（または4スペース、Tab）を入れて字下げする。

- 親項目
  - 子項目1
  - 子項目2
    - 孫項目
- 別の親項目

4. リンクと画像

4-1. リンク

[表示テキスト](https://example.com)

別タブで開く・class を付けるなど細かい指定をしたいときは、HTMLの <a> タグを直接書いてもよい。

4-2. 画像

![代替テキスト](images/example.jpg)

リンクの先頭に ! を付けると画像になる。サイズ指定など細かい制御が要るときは <img> タグを直接書く。

<img src="/images/example.jpg" alt="代替テキスト" width="640">

5. コードブロック

5-1. インラインコード

文章中で1行に収まる短いコードは、バッククオート ` で囲む。

コマンドは `npm install` を実行する。
ファイル名は `package.json`。

本サイトではバッククオートを「コマンド・コードスニペット・ファイル名/パス」にだけ使う運用にしている。固有名詞やサービス名（Cloudflare Pages、GitHub Actions、localStorage など）にはあまり使わない。

5-2. ブロックコード

複数行のコードはバッククオート3つで囲む。

```
普通のコードブロック
```

言語名を指定するとシンタックスハイライトが付く。

```javascript
const greeting = "Hello, World!";
console.log(greeting);
```

本サイトでは言語指定で表示ラベルや色を変えている。terminal はターミナル必須のコマンド、bash はどちらでも実行できるコマンド、prompt は Claude Code への日本語の依頼文、といった感じ。

6. 表

| で列を区切り、2行目に区切り線 --- を入れる。

| 名前 | 用途 |
| --- | --- |
| Markdown | 軽量な記法 |
| HTML | ブラウザ表示用 |

レンダリング結果：

名前	用途
Markdown	軽量な記法
HTML	ブラウザ表示用

--- の左右に : をつけると揃え方を指定できる。

| 左寄せ | 中央 | 右寄せ |
| :--- | :---: | ---: |
| a | b | c |

7. 引用と水平線

7-1. 引用

行頭に > を入れる。

> これは引用文。
> 複数行も書ける。

本サイトでは「補足説明」「用語の注釈」「本筋から外れる雑談」などに使っている。

7-2. 水平線

3つ以上の - または * または _ を行に書く。

---

セクションの大きな区切りや、フッタの前などで使う。

8. フロントマター

ファイルの先頭に --- で囲んでメタデータを書く形式。Astro、Jekyll、Hugo などの静的サイトジェネレーターが記事の情報（タイトル・日付・タグなど）を読み取るために使う。

---
title: 私の最初の記事
description: Markdownで書いたブログ記事
pubDate: "2026-05-22"
tags: ["markdown", "blog"]
---

# 本文ここから

ふつうのMarkdownを続けて書く。

Astroなどでは --- の中身が YAML 形式として解析される。本サイト（vibecoding）の src/*.md にはフロントマターはなく、記事のメタデータは articles.json に分離している。

Markdown 単体にはフロントマターの仕様はない。これは Jekyll が最初に導入した拡張で、いまでは多くのツールが対応している。

9. プレビューする方法

書いた Markdown がどう表示されるかを確認する方法はいくつかある。

9-1. Claudeデスクトップアプリのビューメニュー → ファイル

Claudeデスクトップアプリ（→ CDG）の右上の ビュー メニューから ファイル を開くと、作業フォルダのファイル一覧が表示される。.md ファイルをクリックするとレンダリングされた状態で表示される。Claude Code で記事を書きながらそのままプレビューできるので、最も手間が少ない。

9-2. GitHub.com で見る

GitHub のリポジトリページで .md ファイルをクリックすると、自動でレンダリングされた状態で表示される。インストール不要・ログイン不要（リポジトリが Public なら誰でも見られる）。

表示は GitHub Flavored Markdown（GFM）。GitHub Web UI で記事を編集する流れと組み合わせるとシンプル。

9-3. github.dev のプレビュー機能

GitHub のリポジトリページで . キーを押すと、ブラウザ内に VS Code が立ち上がる（→ GBA 6-4）。.md ファイルを開いて右上の プレビューを開く アイコンをクリックすると、リアルタイムプレビューが見られる。

編集しながら確認したいときに便利。9-2 は閲覧用、9-3 は編集用、というイメージ。

9-4. オンラインエディタ

Dillinger、StackEdit のような Web サービスを使う。左に Markdown を書き込むと右にプレビューがリアルタイム表示される。インストールも GitHub アカウントも不要で、URL を開くだけ。

Dillinger — シンプルなインターフェース、Dropbox/Drive 等への保存も可
StackEdit — 機能豊富、長文編集に向く

下書き用、または GitHub アカウントが無い人向け。本格運用するなら 9-2（GitHub.com）/ 9-3（github.dev）のほうが連携しやすい。

9-5. Claude Code でプレビューアプリを作る

「あえて自分で作る」のもバイブコーディングらしい選択肢。Claude Code に依頼して、Markdown プレビューアプリを自分で作ってしまう。

Markdown を入力すると HTML プレビューがリアルタイムで表示される Webアプリを作って。
画面は左にテキストエリア、右にプレビュー領域の2カラム。
入力内容は localStorage に保存して、リロードしても残るようにして。
HTMLファイル1つ（public/index.html）にまとめて。
Markdown → HTML 変換は CDN から marked.js を読み込んで使って。

これで自分だけのプレビューアプリができる。テーマ・フォント・余白を好みに変える、プレビューの幅を調整するなど、自由にいじれる。Cloudflare にブラウザでアップロードすれば、どこからでもアクセスできるプレビューサイトになる。

9-6. macOS Finder のクイックルック（プラグイン必須）

.md を Finder で選択して スペースキー を押すクイックルックは、macOS 標準では Markdown を解釈してくれず、生のテキストがそのまま表示される。

レンダリングしたい場合は追加プラグインを入れる必要がある。たとえば QLMarkdown を Homebrew でインストールする（Homebrew のセットアップ方法）：

brew install --cask qlmarkdown

その後、システム設定で QLMarkdown の Quick Look 拡張を有効化すると、Finder のスペースキーで Markdown がレンダリング表示されるようになる。

9-7. その他

ローカルの VS Code: .md を開いた状態で Ctrl/Cmd + Shift + V で github.dev と同じプレビューが開く
Slack や Discord の入力欄: 一部のMarkdown記法（太字・コード・リスト）が即時プレビューされる
Notion / Obsidian: 独自方言だがMarkdown互換

10. もっと詳しく

CommonMark Spec — Markdown 標準仕様
GitHub Flavored Markdown Spec — GitHub が使っている拡張版
Markdown Guide — 英語の体系的ガイド

Markdown は表現の幅が広いわけではないが、最低限のテキスト装飾を 書きやすく・読みやすく こなせる。Webサイト・ブログ・README・Slack・Notion など使用シーンが極めて広いので、書き慣れておくと役に立つ場面が多い。

2026-05-22 (last updated: 2026-05-24) タツヲ (yto)

☕️ Vibecoding Notes を応援