読書: Markdown実践入門

最近はAI活用のためにMarkdownを書く頻度も増えてきたので、すぐに調べられる辞書として購入した本。

書き方はググればわかるでしょと言われるとその通りなのですが、都度ググったりAIに聞いたりするとスピードが若干落ちるので。

そういった辞書用途なので、買うならば「紙媒体じゃないと使えない」と思います。

この本は、半分ぐらいが「Markdownの基礎や活用術の説明」になっていて、Markdownを知らない新入社員にも使える内容になっていますが、Markdownを書いたことのある人は読み飛ばして良さそう。

で、残り半分ぐらいが辞書(Markdown記法のリファレンス)になっています。

例えば、「リンクは[]と()のどっちだっけ？」といった疑問も1秒で調べられるのが助かっています。

あと、良いと感じるところは、サービス毎の記法がカバーできている点。(実はMarkdownはサービスによって対応している書き方が異なる)

例) 文字装飾の書き方

こういった基礎的な記法以外にも、
・フローチャート表現に使える「Mermaid記法」
・複雑な数式を表現する際に使える「LaTex(ラテフ)記法」
といった業務上で調べたい記法が一式揃っているのが嬉しい。

参考までに書かれている文法は以下の通り。

・見出し
・文字装飾(太字、斜体、取り消し線)
・リスト(箇条書き、番号付き、タスクリスト)
・リンク
・画像
・引用
・コードブロック
・表
・水平線
・段落と改行
・脚注
・アンカーリンク
・アラート・コールアウト(note、info、warn、alert）
・フローチャート(Mermaid)
・数式表現
・折りたたみ
・HTML埋め込み
・エスケープ

以下、書籍情報

「書く技術」と「伝える力」を、Markdownで身につける。

ITエンジニアにとって、コードを書く技術と同じくらい重要なのが「ドキュメントを書く技術」です。設計書、仕様書、README、議事録、チーム内の情報共有──日々の業務で扱うドキュメントは多岐にわたります。

これらすべてに共通する書式が「Markdown」です。GitHub、Slack、Teams、Notion、Obsidian、そして生成AIへのプロンプト。MarkdownはITエンジニアにとっての”書く技術”であるだけでなく、生成AIと正しく対話するための共通言語でもあります。ITエンジニアの業務環境において、Markdownはもはや「一般教養」となっています。

しかし、初級ITエンジニアの多くが抱える課題は「Markdown記法とは？」「どんな場面でどう使うのかが分からない」というものです。基本的な記法を知っていたとしても、実務での使いどころや、効果的な活用方法を体系的に学ぶ機会がありませんでした。

本書は、初級ITエンジニアが実務で直面する「書く場面」「伝える場面」での課題を想定し、Markdownの基礎から実践、各ツールでの活用、さらにはリファレンス（方言対応を含む）まで、体系的に解説する実践入門書です。

こんな方にオススメ
・Markdownを基礎から体系的に学びたい初級ITエンジニア
・Markdownの書き方がプラットフォームごとに違って戸惑っている方
・生成AIへの指示を効果的に構造化したい方
・チームのドキュメント品質を底上げしたいリーダー層

出典:技術評論社: ITエンジニアのためのMarkdown実践入門

目次
第1章　Markdownが活きる場面
1.1　ITエンジニアの日常とMarkdown
　1.1.1　さまざまな職種で求められる「書く」スキル
　1.1.2　テキストで伝える仕事だからこそ
1.2　Markdownが使われる場面
　1.2.1　ドキュメント作成
　1.2.2　チーム共有＆ナレッジ管理
　1.2.3　情報発信
　1.2.4　生成AI活用
　1.2.5　その他のMarkdown対応ツール
1.3　Markdownを学ぶメリット
　1.3.1　手軽に始められる
　1.3.2　使える場面が広い
　1.3.3　長く使える
1.4　本書の構成と読み方
　1.4.1　本書の構成
　1.4.2　読者タイプ別の読み方
　1.4.3　本書で扱わないこと
　1.4.4　サンプルの読み方
　1.4.5　本書の表記について
　1.4.6　動作確認環境
【コラム】デジタル庁も推進するMarkdown

第2章　Markdownの基礎
2.1　Markdownとは何か
　2.1.1　Markdownの誕生
　2.1.2　設計思想は「読みやすさが優先」
　2.1.3　Markdownの本質：テキストに構造を与える記法
　2.1.4　HTMLとの関係
2.2　プレーンテキストの強み
　2.2.1　可搬性：どこでも開ける、いつまでも読める
　2.2.2　バージョン管理との相性：差分が見える
　2.2.3　ツールを選ばず扱える
　2.2.4　Markdownが適さない用途
2.3　基本的な考え方
　2.3.1　構造を意識して書く
　2.3.2　「方言」の問題
　2.3.3　方言との付き合い方
2.4　まず覚える7つの記法
　2.4.1　見出し：文書に構造を与える
　2.4.2　リスト：情報を整理して伝える
　2.4.3　コードブロック：コードやコマンドを明示する
　2.4.4　引用：他者の言葉を区別する
　2.4.5　太字・取り消し線：重要な語句を強調する
　2.4.6　リンク：参照先を示す
　2.4.7　表：データを整理して見せる
　2.4.8　基本記法を組み合わせる
2.5　実際に書いてみよう
　2.5.1　オンラインエディタで試す
　2.5.2　Windowsメモ帳で始める
　2.5.3　macOSのメモアプリで始める
　2.5.4　ハンズオン演習
【コラム】Markdownを支えるGFM公式仕様書

第3章　ドキュメント作成での活用術
3.1　READMEの書き方
　3.1.1　コードが本文に埋もれるREADME
　3.1.2　プロジェクト概要の伝え方
　3.1.3　インストール手順の書き方
　3.1.4　使用例の示し方
　3.1.5　READMEの全体構成
3.2　設計書・仕様書の書き方
　3.2.1　パラメータが文章に溶けた設計書
　3.2.2　見出し階層とセクション設計
　3.2.3　API仕様の書き方
　3.2.4　要件とインフラ構成の整理
3.3　議事録の書き方
　3.3.1　決定事項が探せない議事録
　3.3.2　見出しとリストで構造化する
　3.3.3　タスクリストの活用
3.4　技術ブログの書き方
　3.4.1　読みやすい記事構成
　3.4.2　コードの効果的な見せ方

第4章　生成AIでの活用術
4.1　なぜMarkdownで生成AIの回答の質が上がるのか
　4.1.1　構造化された入力の例
　4.1.2　生成AIに伝わるMarkdownの書き方
　4.1.3　生成AIの回答をMarkdownで受け取る
4.2　作りたいものを相談する
　4.2.1　機能の実装方針を相談する
　4.2.2　技術選定を相談する
　4.2.3　構成を相談する
4.3　コードの相談・レビューを依頼する
　4.3.1　コードと説明を分ける
　4.3.2　エラーを相談する
　4.3.3　コードレビューを依頼する
4.4　ドキュメントを生成する
　4.4.1　テンプレートで出力形式を指定する
　4.4.2　コードからドキュメントを生成する
4.5　AIの回答を活用する
　4.5.1　Markdown形式で回答を受け取る
　4.5.2　会話をナレッジとして残す
【コラム】コーディングエージェントとMarkdown

第5章　チーム共有＆ナレッジ管理での活用術
5.1　チャットで情報を構造化して伝える（Slack・Teams）
　5.1.1　チャットは「1発で伝わる」が理想
　5.1.2　報告・共有のメッセージ
　5.1.3　質問・依頼のメッセージ
　5.1.4　まとめ
5.2　Markdownで情報を蓄積する（Notion・Obsidian）
　5.2.1　Notionでチームドキュメントを書く
　5.2.2　Obsidianで個人ナレッジを積み上げる
　5.2.3　ツールは変わる、Markdownは残る
【コラム】Markdown方言はなぜ生まれたのか

第6章　Markdown活用を加速するツール
6.1　編集環境を整える
　6.1.1　組み込み機能だけでここまでできる
　6.1.2　拡張機能でさらに便利に
　6.1.3　Markdown編集に役立つ設定（settings.json）
6.2　markdownlintで品質を保つ
　6.2.1　設定ファイルを作る
　6.2.2　よく調整するルール
　6.2.3　保存時の自動修正
　6.2.4　チーム開発での活用
6.3　Markdownから成果物を作る
　6.3.1　Marp ─ Markdownでスライドを作る
　6.3.2　LibreOffice ─ MarkdownをPDF・Wordに変換する
　6.4　明日の会議から始めよう
【コラム】人間にも、AIにも伝わるドキュメント

第7章　Markdown文法リファレンス ― 基礎編
リファレンスの読み方
各節の構成
入力と表示結果の見方
方言対応表の見方
推奨する書き方について
7.1　見出し
　7.1.1　基本構文
　7.1.2　記述例と表示結果
　7.1.3　推奨する書き方
　7.1.4　方言対応表
　7.1.5　よくある間違いと対処法
　7.1.6　関連する記法
7.2　文字装飾
　7.2.1　基本構文
　7.2.2　記述例と表示結果
　7.2.3　推奨する書き方
　7.2.4　方言対応表
　7.2.5　よくある間違いと対処法
　7.2.6　関連する記法
7.3　リスト
　7.3.1　基本構文
　7.3.2　記述例と表示結果
　7.3.3　推奨する書き方
　7.3.4　方言対応表
　7.3.5　よくある間違いと対処法
　7.3.6　関連する記法
7.4　リンク
　7.4.1　基本構文
　7.4.2　記述例と表示結果
　7.4.3　推奨する書き方
　7.4.4　方言対応表
　7.4.5　よくある間違いと対処法
　7.4.6　関連する記法
7.5　画像
　7.5.1　基本構文
　7.5.2　記述例と表示結果
　7.5.3　推奨する書き方
　7.5.4　方言対応表
　7.5.5　よくある間違いと対処法
　7.5.6 関連する記法
7.6　引用
　7.6.1　基本構文
　7.6.2　記述例と表示結果
　7.6.3　推奨する書き方
　7.6.4　方言対応表
　7.6.5　よくある間違いと対処法
　7.6.6　関連する記法
7.7　コードブロック
　7.7.1　基本構文
　7.7.2　記述例と表示結果
　7.7.3　推奨する書き方
　7.7.4　方言対応表
　7.7.5　よくある間違いと対処法
　7.7.6　関連する記法
7.8　表
　7.8.1　基本構文
　7.8.2　記述例と表示結果
　7.8.3　推奨する書き方
　7.8.4　方言対応表
　7.8.5　よくある間違いと対処法
　7.8.6　関連する記法
7.9　水平線
　7.9.1　基本構文
　7.9.2　記述例と表示結果
　7.9.3　推奨する書き方
　7.9.4　方言対応表
　7.9.5　よくある間違いと対処法
　7.9.6　関連する記法
7.10　段落と改行
　7.10.1　段落の基本
　7.10.2　段落内での改行
　7.10.3　記述例と表示結果
　7.10.4　推奨する書き方
　7.10.5　方言対応表
　7.10.6　よくある間違いと対処法
　7.10.7　関連する記法

第8章　Markdown文法リファレンス ― 応用編
応用編の読み方
8.1　脚注
　8.1.1　基本構文
　8.1.2　記述例と表示結果
　8.1.3　推奨する書き方
　8.1.4　方言対応表
　8.1.5　よくある間違いと対処法
　8.1.6　関連する記法
8.2　アンカーリンク
　8.2.1　基本構文
　8.2.2　記述例と表示結果
　8.2.3　推奨する書き方
　8.2.4　方言対応表
　8.2.5　よくある間違いと対処法
　8.2.6　関連する記法
8.3　目次の自動生成
　8.3.1　基本構文
　8.3.2　推奨する書き方
　8.3.3　方言対応表
　8.3.4　関連する記法
8.4　アラート・コールアウト
　8.4.1　基本構文
　8.4.2　記述例と表示結果
　8.4.3　推奨する書き方
　8.4.4　方言対応表
　8.4.5　よくある間違いと対処法
　8.4.6　関連する記法
8.5　フローチャート・図表現（Mermaid）
　8.5.1　対応する図の種類
　8.5.2　基本構文
　8.5.3　記述例と表示結果
　8.5.4　その他のMermaid図
　8.5.5　推奨する書き方
　8.5.6　方言対応表
　8.5.7　よくある間違いと対処法
　8.5.8　関連する記法
8.6　数式表現
　8.6.1　基本構文
　8.6.2　記述例と表示結果
　8.6.3　推奨する書き方
　8.6.4　方言対応表
　8.6.5　よくある間違いと対処法
　8.6.6　関連する記法
8.7　折りたたみ
　8.7.1　基本構文
　8.7.2　記述例と表示結果
　8.7.3　推奨する書き方
　8.7.4　方言対応表
　8.7.5　関連する記法
8.8　HTML埋め込み
　8.8.1　基本構文
　8.8.2　記述例と表示結果
　8.8.3　推奨する書き方
　8.8.4　方言対応表
　8.8.5　よくある間違いと対処法
　8.8.6　関連する記法
8.9　エスケープ
　8.9.1　基本構文
　8.9.2　記述例と表示結果
　8.9.3　推奨する書き方
　8.9.4　方言対応表
　8.9.5　関連する記法
8.10　その他の記法
　8.10.1　ハイライト
　8.10.2　絵文字ショートコード
　8.10.3　Base64インライン画像
　8.10.4　Front Matter（メタデータ）
　8.10.5　方言対応表

出典:技術評論社: ITエンジニアのためのMarkdown実践入門