はじめに
現在、Vibe Coding でデスクトップ版の Markdown Editor を開発しています。
Windows / macOS / Linux に対応していて、Free Forever で公開しています。
ただ今回は、「どこまで実装できたか」を伝える機能テスト記事ではなく、Markdown を学びたい人が、その場で試しながら身につけられる記事 としてまとめることにしました。
Markdown は、覚えるだけではなかなか定着しません。
実際に書いて、表示を見て、少し直して、もう一度書いてみる。
この繰り返しがいちばん理解につながると感じています。
AI 時代に入って、これからのドキュメントには「人が読みやすいこと」と「AI が扱いやすいこと」の両方がますます求められるはずです。
その中で Markdown は、今後さらに重要になるフォーマットのひとつだと思っています。
そこでこの記事では、、以下の Qiita 記事で紹介されている Markdown 記法を題材にして、学びながらその場で試せるように** まとめました。
マークダウン記法は奥深く、楽しい — テキストだけで「伝わるドキュメント」を作る技術
サンプルをそのままコピペして練習できるので、読むだけで終わらず、そのまま手を動かしてみてください。
最新版のダウンロードはこちらです。
https://github.com/engchina/no.1-markdown-editor/releases
この記事で学べること
- Qiita でよく使う Markdown 記法の基本
- 表、コード、数式、Mermaid の実践的な書き方
- サンプルを少し変えながら覚える練習方法
- 「知っている」ではなく「自分で書ける」状態になるための使い方
この Editor を学習に使うメリット
Markdown は、見本を見るだけよりも、自分で少し書き換えてみる 方がずっと早く身につきます。
この Editor では、たとえば次の流れで学べます。
- 記事のサンプルを貼る
- 単語や見出しを自分の内容に変える
- すぐに表示を確認する
- 崩れたところを直す
- 小さな記事として完成させる
この「読む → 試す → 直す → もう一度書く」の流れが、いちばん定着しやすいと感じています。
1. まずは基本記法から
1.1 テキスト装飾
強調、補足、コードの区別ができるだけで、文章はかなり読みやすくなります。
**太字** は重要な箇所に使います。
*斜体* は軽い強調や英語表現に向いています。
~~打ち消し線~~ は修正や古い情報の取り消しに使えます。
`インラインコード` は関数名や変数名、コマンド名に便利です。
書き方を覚えるだけでなく、「どこに使うと読みやすくなるか」まで意識すると、記事の質が上がります。
練習してみること
- 自己紹介を3行書く
- その中で
インラインコードを1つ使う - いちばん伝えたい言葉を 太字 にする
1.2 見出し
見出しは、記事の読みやすさを決めるいちばん大事な要素のひとつです。
# H1 — 記事タイトル（基本は1記事に1つ）
## H2 — 大きな話題
### H3 — H2の中の小見出し
#### H4 — 補足や詳細
見出しを正しく使うと、読者は「今どこを読んでいるか」がすぐにわかります。
逆に、見出しの粒度がバラバラだと、内容が良くても読みにくく感じられます。
練習してみること
「Markdown を学ぶ手順」というテーマで、H1〜H3 まで使ってミニ構成を作ってみてください。
1.3 リスト
手順、要点、TODO を整理したいときに便利です。
- 箇条書き1
- 箇条書き2
- ネストした項目
1. 番号付き1
2. 番号付き2
- [ ] 未完了タスク
- [x] 完了タスク
チェックリストまで使えるようになると、記事だけでなく個人メモや進捗管理にも応用できます。
練習してみること
今日やることを3つ、チェックリストで書いてみてください。
2. テーブルが書けると、比較記事が一気に読みやすくなる
Markdown の表は、サービス比較、技術選定、仕様整理でとても役立ちます。
| 項目 | Markdown | HTML | Word |
|---|---|---|---|
| バージョン管理 | ◎ テキストなので diff が明確 | △ タグが冗長 | × バイナリ |
| 表示速度 | ◎ 軽量 | ○ ブラウザ依存 | △ アプリ起動が必要 |
| 共同編集 | ◎ Git で管理しやすい | ○ 可能 | △ 競合しやすい |
さらに、列の配置も指定できます。
| 左寄せ | 中央寄せ | 右寄せ |
|:---|:---:|---:|
| left | center | right |
| A | B | C |
表は「情報を圧縮して伝える」力がとても強いので、覚えておくと実務でもかなり使えます。
練習してみること
自分がよく使う言語、フレームワーク、エディタなどを3項目以上で比較表にしてみてください。
3. コードブロックは、技術記事の読みやすさを大きく左右する
コードをそのまま文章の中に混ぜるより、ブロックとして分けたほうが圧倒的に読みやすくなります。
```python
def hello():
print("Hello, Markdown!")
```
言語名を付けておくと、あとから見返したときにも内容がわかりやすくなります。
現時点の Editor では、コードブロックの表示とシンタックスハイライトは OK です。
練習してみること
- 好きな言語で関数を1つ書く
- コードブロックの上に、そのコードの説明を2行だけ書く
この2つをセットでやると、「コードを書く力」と「説明する力」を同時に練習できます。
4. 数式も Markdown で扱えると表現の幅が広がる
数式を使う記事は難しく見えがちですが、基本を覚えると意外とシンプルです。
4.1 インライン数式
文章の途中に数式を入れたいときは、$...$ を使います。
1日1%の成長を365日続けると $1.01^{365} \fallingdotseq 37.8$ 倍になります。
サンプルの効果：
1日1%の成長を365日続けると $1.01^{365} \fallingdotseq 37.8$ 倍になります。
4.2 ブロック数式
独立した式として見せたいときは、ブロックで書くと見やすくなります。
```math
\sum_{i=1}^{n} a_i = a_1 + a_2 + \cdots + a_n
```
サンプルの効果：
\sum_{i=1}^{n} a_i = a_1 + a_2 + \cdots + a_n
数式が使えるようになると、アルゴリズム、統計、機械学習、最適化などの記事が一気に書きやすくなります。
練習してみること
次のどちらかを、自分で書いて表示を確認してみてください。
- 二次方程式の解の公式
- 平均、分散、総和のいずれか1つ
5. Mermaid を使うと、図もテキストで管理できる
Mermaid は、フローチャートやシーケンス図などをテキストから生成できるので、Markdown ととても相性が良いです。
画像を手で作るより差分管理しやすく、あとから修正もしやすいのが大きなメリットです。
5.1 フローチャート
```mermaid
graph TD
A[開始] --> B{条件分岐}
B -->|Yes| C[処理A]
B -->|No| D[処理B]
C --> E[終了]
D --> E
```
サンプルの効果：
練習してみること
「ログイン処理」や「お問い合わせ送信」など、身近な処理をフローチャートにしてみてください。
5.2 シーケンス図
```mermaid
sequenceDiagram
participant U as ユーザー
participant F as フロントエンド
participant A as API
participant D as DB
U->>F: ログインボタンクリック
F->>A: POST /api/login
A->>D: SELECT * FROM users
D-->>A: ユーザー情報
A-->>F: JWT トークン
F-->>U: ダッシュボード表示
```
サンプルの効果：
処理の流れを時系列で説明したいときにとても便利です。
5.3 ER 図
```mermaid
erDiagram
USER ||--o{ POST : writes
USER {
int id PK
string name
string email
}
POST ||--o{ COMMENT : has
POST {
int id PK
string title
text body
int user_id FK
}
COMMENT {
int id PK
text body
int post_id FK
}
```
サンプルの効果：
テーブル設計やデータ構造の共有に向いています。
5.4 ガントチャート
```mermaid
gantt
title プロジェクトスケジュール
dateFormat YYYY-MM-DD
section 設計
要件定義 :a1, 2026-04-01, 7d
基本設計 :a2, after a1, 5d
section 開発
バックエンド :b1, after a2, 14d
フロントエンド :b2, after a2, 14d
section テスト
結合テスト :c1, after b1, 7d
```
サンプルの効果：
設計から実装、テストまでの流れを共有したいときに便利です。
5.5 そのほかの Mermaid も試せる
たとえば、Git の流れを表す gitGraph や、割合を見せる pie も使えます。
```mermaid
gitGraph
commit id: "初回コミット"
branch feature/login
commit id: "ログイン画面実装"
commit id: "バリデーション追加"
checkout main
merge feature/login id: "PR #1 マージ"
```
サンプルの効果：
```mermaid
pie title 開発工数の内訳
"設計" : 15
"実装" : 45
"テスト" : 25
"ドキュメント" : 15
```
サンプルの効果：
最初から全部覚えなくても大丈夫です。
まずは フローチャート → シーケンス図 → ER 図 の順で触ると覚えやすいと思います。
6. 折りたたみを使うと、長い情報も読みやすくなる
Qiita 独自の Note 記法もありますが、まず覚えやすくて再利用しやすいのは <details> を使った折りたたみです。
<details><summary>クリックで展開</summary>
長いログや補足説明、あとで読みたいコードなどを入れられます。
```python
for i in range(5):
print(f"Line {i}")
```
</details>
サンプルの効果：
クリックで展開
長いログや補足説明、あとで読みたいコードなどを入れられます。
for i in range(5):
print(f"Line {i}")
長い記事ほど、「全部を最初から見せない」工夫が読みやすさにつながります。
練習してみること
補足説明、長いログ、参考コードのどれかを折りたたみで1つ作ってみてください。
7. 読むだけで終わらせず、実際に身につけるための使い方
Markdown は、記法一覧を眺めるだけではなかなか定着しません。
実際に使えるようになるには、小さく書いて、すぐ確認して、少しずつ増やす のがいちばんです。
おすすめは、次の順番です。
- この記事のサンプルをそのまま Editor に貼る
- 単語を自分のテーマに置き換える
- 見出し・表・コードブロックを1つずつ追加する
- 最後に Mermaid か数式を1つ入れる
- 300〜500文字くらいのミニ記事として完成させる
ここまでやると、「見たことがある」から「自分で書ける」へ変わります。
8. AI 連携も、Markdown 学習を後押しできるように育てている
この Editor では、OpenAI と OCI Enterprise AI との連携も進めています。
現時点では、AI 連携そのものはすでに実装できていますが、今はまだ 実用的に学習や執筆を助けられる形にするための調整段階 です。
個人的には、AI は「自動で全部書く」ためだけではなく、
- 記法の意味をすぐ確認する
- 練習用のテーマを作る
- 書いた文章の構成を見直す
といった形で、学びを加速する補助輪 として使うのが相性がいいと感じています。
まとめ
今回の記事では、開発中の Markdown Editor を紹介しながら、Qiita でよく使う Markdown 記法を、学んで・試して・練習して・身につける ことを主眼にまとめました。
特に、次の項目は実務でもそのまま役立ちます。
- 基本的な Markdown 記法
- テーブル
- コードブロック
- LaTeX 数式
- Mermaid による図表現
- 折りたたみ表現
Markdown は、覚えること自体が目的ではなく、伝わる記事やドキュメントを、自分の力で書けるようになること が大切です。
そのためには、読むだけでなく、実際に手を動かして試すのがいちばんです。
最新版のダウンロードはこちらです。
https://github.com/engchina/no.1-markdown-editor/releases
この記事は、必要になったときに見返せるよう ストックしておくと便利 だと思います。
役に立ったら いいね や ストック をしてもらえるとうれしいです。
また、「こんな練習問題があると助かる」「この記法も学びたい」といった声も大歓迎です。