マークダウン記法 | プログラミングラボ

マークダウン記法とは

Markdown は「読みやすさ」を重視した軽量マークアップ言語です。
テキストで素早く書く → ツールでHTML等に変換 という流れで、ドキュメント・README・議事録・ナレッジ管理などに広く使われます。

代表的な実装: CommonMark / GFM（GitHub Flavored Markdown） / Pandoc など。

概要

特長

可読性が高い（生テキストがそのまま読みやすい）
学習コストが低い（基本10分）
差分管理/Git との相性が良い

主な用途

README / CHANGELOG / ISSUE / PR テンプレ
社内ドキュメント・議事録・仕様書の草案
ブログやCMSの本文（MD対応テーマ）

拡張

GFM: 表、チェックボックス、コードフェンス言語
Pandoc: 図表番号、文献、目次、LaTeX数式
MDX: JSXと併用してコンポーネント化

基本

やりたいこと	書き方（左）→ 表示（右）
見出し	`# H1` 〜 `###### H6`
段落/改行	空行で段落。行末に半角スペース2つで改行。
強調	`太字`、`斜体`、`~~取り消し~~`
リンク	`[テキスト](https://example.com)`
画像	`![代替テキスト](path/to.png)`
箇条書き	`-` / `*` / `+`、番号付きは `1.`
引用	`> 引用`
コード	インラインは `code`、ブロックは ```lang 〜 ```
水平線	`---` / `***` / `___`

最小チートシート

# タイトル

本文。改行は末尾にスペース2つ。  
**太字** と *斜体*、~~取消~~、`code`

- リスト1
- リスト2
  - ネスト

1. 番号付き
2. つづき

> 引用

```js
console.log("コードフェンス");
```

[リンク](https://example.com) と ![画像](img.png)

基礎（書式のコツ）

改行・段落

段落は空行で区切る
強制改行は「行末にスペース2つ」
表やコード直後は空行を入れると崩れにくい

画像

代替テキスト（alt）を入れてアクセシビリティ担保
相対パスはリポジトリの構造に合わせる

リンク

参照式リンクも可：[text][id] と [id]: URL "title"
長URLはフットノートや末尾にまとめると読みやすい

コード

言語指定でハイライト（例：```js）
Shellは先頭に $ を付けないとコピペしやすい

応用（GFM などの拡張）

表（Tables）

| 列A | 列B |
|:--|--:|
| 左寄せ | 右寄せ |

タスクリスト

- [ ] TODO
- [x] DONE

※対応はビューアー依存。GitHub等ではそのままチェック表示。

図式・数式（非標準）

Mermaid：```mermaid 〜（対応ツールで描画）
数式： $...$ / $$...$$（KaTeX/MathJaxなど）

```mermaid
flowchart LR
  A[Start] --≷ B{OK?}
  B -- Yes --≷ C[Go]
  B -- No  --≷ D[Stop]
```

発展（ワークフロー）

プロジェクト文書化

README / CONTRIBUTING / SECURITY / CODE_OF_CONDUCT
CHANGELOG（Keep a Changelog 方式など）
ISSUE / PR テンプレ（.github/ 以下）

変換・配信

Pandoc で PDF/HTML/DOCX へ変換
静的サイト（Docsify, Docusaurus, Astro など）

拡張エコシステム

MDX（React/Next.jsと併用）
Front matter（YAML）でメタ情報

目的

情報共有の速度と品質を両立
Git で変更履歴や差分が見やすい
エンジニア以外でも学びやすい

仕事の現場（ベストプラクティス）

DO

1文1意、短文・短段落
章・節を見出しで整理、章内目次を付ける
画像は代替テキスト＋相対パス
コードはフェンス＋言語指定

DONT

HTML混在の乱用（必要最低限に）
私的略語・表記ゆれの放置
URLの裸貼り（リンクテキストを付ける）

そのほかの記法と比較

記法	強み	弱み	向き・不向き
Markdown	軽量・可読性・普及	厳密な目次/図表/参照は拡張依存	README・ナレッジ・ブログ
AsciiDoc	機能豊富・参照/属性が強い	やや学習コスト	大規模ドキュメント
reStructuredText	Sphinx連携・豊富な拡張	素の可読性はMarkdownに劣る	Pythonドキュメント
HTML	表現自由度・厳密	記述量が多い	最終出力・細かい制御

知っておくといい

知識

CommonMark / GFM の差分
Front matter（YAML）
レンダラごとの制約（GitHub/Wiki/CMS）

技能

章立てと目次設計
表・図の最小限の表現力
テンプレ化・再利用

用語・ルール

フェンスコード / インラインコード
ハードブレーク / ソフトブレーク
Trailing spaces と Lint（markdownlint 等）

例

README テンプレ

# プロジェクト名

概要を1-3行で。

## 特長
- 箇条書き

## セットアップ
```bash
# 依存関係
npm i
# 開発
npm run dev
```

## 使い方
1. 手順A
2. 手順B

## ライセンス
MIT

議事録テンプレ

# 議事録 YYYY-MM-DD

- 参加者: A, B, C
- 目的: ○○の決定

## 決定事項
- ○○を採用

## TODO
- [ ] だれが / いつまでに / 何を

ライブプレビュー

Markdown（入力）

プレビュー（参考実装）

※簡易パーサ実装。CommonMark/GFMの一部に対応（厳密な互換は保証しません）。

マークダウン記法 Markdown