マークダウン記法は奥深く、楽しい — テキストだけで「伝わるドキュメント」を作る技術 - Qiita

この記事は約4分で読めます。 マークダウン記法は奥深く、楽しい — テキストだけで「伝わるドキュメント」を作る技術 はじめに 皆さんは Markdown（マークダウン） を「見出しと箇条書きが書ける記法」程度に思っていませんか？ 私もかつてはそうでした。しかし、個人開発で REQUIREMENTS.md / SPECIFICATION.md / DESIGN.md などの技術ドキュメントを Markdown で書き続けるうちに、「テキストだけでここまで表現できるのか」 と驚く場面が何度もありました。 この記事では、Markdown の基本から Mermaid による図表描画、さらに Qiita 独自の拡張記法まで、「知っているだけで生産性が変わる」 テクニックを体系的に紹介します。

[ku__ra__ge]

mermaid.jsはマジ便利だが、それはたまたまqiita書式に組み込まれてるだけでmarkdownとは別プロダクトなんだよなあ。

[kamiokando]

ドキュメントで小澤征爾さんが楽譜を見るだけで感動して涙を流すシーンがあったんだけど、慣れるとマークダウン見るだけで整って見えるんだろうか？

[stabucky]

半分はMarkdownでなくMarmaidの話になっている。Markdownは見出しと本文と箇条書きの使い方が基本であり重要である。

[sisya]

3以降は通常のmarkdownでは使えないので、記事の大半が関係ない話になってしまっている。markdownはもう少し各所の独自ルールを取り込んで拡張規定をつくってくれないものか。

[wwestpp]

マークダウン形式は必要な知識になりそう

[jeeraa]

やっぱり表かぁ。神エクセルを彷彿とさせる。時代の呪文だ。

[misshiki]

Markdownの基本記法から、表・コード・数式・Mermaid・Qiita独自記法までを体系的に紹介する記事。特にMermaidで図をテキスト管理でき、Git diffや共同編集と相性が良い点を実例付きで整理している。

[acealpha]

markdownは重要だと言われてるけど、今生成AI使ってて自分でmarkdown作ることほぼなくない？

[fa11enprince]

“「テキストだけでここまで表現できるのか」 と驚く場面が何度もありました。”/それMarkdownでなくMermaidでは？Markdownの果たした役割はすごいが控えめに言って後ろスペース2個がクソ。方言でなくても良いものもある。

[tallmen]

テキストの構造化、インデントでネストさせる書き方が本質と思ってる

[FreeCatWork]

マークダウン？ボクも cute に書けるように頑張るにゃ！

[TakamoriTarou]

あ゛？マークダウン記法ってあれでしょ？はてな記法のパクリでしょ？（違います　　もともとはてな記法ネイティブだったが、最近ではすっかりMarkdownとのバイリンガル（これも違う

[hiroyuki1983]

全てはExcelに通じる。Excelは唯一神

[gyampy]

便利そう

[shira0211tama]

ほならXMLの方がもっと良いのでは？

[xiangze]

Mermaid

[kotesaki]

メモ

[ndanna]

便利

[knitcapmann]

gitで管理しやすい & AIでの利用に向いてるのは利点だけど、直感的に図形描画できないのはつらい。

[ravell]

手段が目的になってるやつ。

[taguch1]

marmeidで雑に絵も描けてここ10年くらいは必要充分だとは思ってる

[nguyen-oi]

結局Mermaidとか凝りすぎて「テキストだけでシンプルに」という初心を忘れていくのが様式美。エンジニアのドキュメント作成時間の半分はこれに溶けてる説