Markdown

Markdownで図表を綺麗に書く方法 対象読者と実行環境 対象読者：Markdown初級〜中級者、図表（特にフローチャートや関係図）を綺麗に描きたい人 想定環境： Markdown対応エディタ（Typora、Visual Studio Code + Mermaid Preview 拡張など） GitHubやObsidian、DocsifyなどのMermaid対応ビューア 1. Mermaidとは何か？ Mermaidは、Markdown内でフローチャート、シーケンス図、ガントチャート、クラス図などを簡潔な記法で描画できるツールです。 flowchart TD A[開始] --> B{条件分岐} B -- はい --> C[処理1] B -- いいえ --> D[処理2] C --> E[終了] D --> E 対応ビューアでは自動で図が生成されます。 2. Mermaidの基本構文 2.1 フローチャート flowchart LR A[入力] --> B[処理] --> C[出力] 2.2 シーケンス図 sequenceDiagram participant ユーザー participant サーバー ユーザー->>サーバー: リクエスト サーバー-->>ユーザー: レスポンス 2.3 ガントチャート gantt dateFormat YYYY-MM-DD title プロジェクトスケジュール section 開発 設計 :a1, 2024-05-01, 5d 実装 :after a1, 10d テスト :2024-05-20, 5d 3. Mermaid記法を綺麗に整えるコツ 3.1 ノードのラベルを簡潔にする 長すぎると読みにくくなる 3.2 ノード配置を意識する flowchart TD（縦）、LR（横）などレイアウト方向を選ぶことで見やすくなる 3.3 必要ならサブグラフで整理 flowchart TD subgraph フローA A1 --> A2 end subgraph フローB B1 --> B2 end A2 --> B1 4. Mermaidに対応したエディタとツール ツール/エディタ Mermaid対応 備考 VSCode + Mermaid拡張 ○ リアルタイムプレビュー可能 Obsidian ○ 標準でMermaid対応 Docsify + plugin ○ Webサイトでも描画可能 Typora △（一部） バージョンや設定により異なる GitHub ○ Mermaid記法の直接埋め込みに対応 5. Mermaidの制限と注意点 大規模な図は視認性が下がるため分割推奨 Markdownビューアごとに描画の差異がある 古いビューアはMermaid未対応のこともある まとめ Mermaidを使えば、Markdownでも綺麗な図表が書ける フローチャート、シーケンス図、ガントチャートなどが簡単に描ける VSCodeやObsidianなどの環境で効率よく可視化 Markdownでの文書管理に図解を加えると、情報の伝達力が大きく向上します。Mermaidを活用して、読みやすく美しい技術資料を書きましょう。 ...

MarkdownユーザーがAsciidocを試してみた｜使いやすさ・欠点・移行の所感 この記事でわかること MarkdownとAsciidocの主な違い Asciidocを使って感じたメリット・デメリット 実際の使用例と学習コストの印象 Markdownからの移行はおすすめできるのか？ Markdownの限界 Markdownで記事をずっと書いてきたが、そろそろ限界を感じていた。ルビが振れない。表が書きにくい。数式が表示できない。…そんな中で見つけたのが「Asciidoc」だった。 はじめは軽い気持ちだった。「ちょっと試してみるか」程度で始めたものの、いざ書き始めてみると、予想以上にしっくりきた。「これ、最初からこっちで書いていればよかったのでは？」とすら感じるほどだった。Asciidocの思想は、“なんとなく書ける”Markdownとは違い、“最初から構造的に書く”という方向に向いている。 使い慣れているMarkdownと比べて何がどう違い、どこに惹かれたのかを、ここに記録しておく。 MarkdownからAsciidocに興味を持った理由 Markdownは軽量で便利だが、「構造化された長文」を扱うには力不足だと感じるようになった。特に以下の点で不満があった： 表記の自由度が低い（脚注・ルビ・図番号など） 表が複雑になると地獄（パイプ区切りの視認性） 数式を書こうとするとKaTeXやMathJax頼りで面倒 ファイル構造やテンプレートとの連携に限界がある そんな中で「Asciidocは本格的な技術ドキュメントのために作られた」「見出し構造や属性が自然」「PDFやHTML、EPUBにも出力可能」といった紹介を見て、試してみたくなった。 各記法の詳細等は、Qiitaなどで調べればいくらでも出てくるので割愛するが、以下に実際に使ってみて感じたことを記す。 Asciidocを使って感じた4つのメリット 1. 見出しやリストのネストが、MediaWiki記法に近い Asciidocでの記法 == 見出し * 箇条書き ** ネスト1 *** ネスト2 Markdownのように見出しに#を使うか、asciidocのように=を使うかは、単なるルールの違いのため、どちらが良いとは言えないが、個人的にWikipediaなどのMediaWiki記法には馴染みがあるため、asciidocのように見出しに=を使うというのは、書く上で慣れていて嬉しい。逆に、MediaWiki記法に慣れた状態から、初めてMarkdownを触ったときは、#を使うのに戸惑ったくらいだ。 箇条書き及びネストについては、asciidocの仕様はMediaWiki記法そのものである。個人的にMarkdownのネストの仕様は好きでは無かった。Markdownでは、箇条書きをネストする場合、以下のように空白文字でインデントする必要がある。空白文字でのコントロールは視認性に劣ると感じている。 Markdownでの記法 * 箇条書き * ネスト1 * ネスト2 2. テーブルがCSV形式で書ける Asciidocでの記法 [format="csv", opstions="header"] |====== a, b, c 1, 2, 3 4, 5, 6 |====== csv形式で書けるのが地味に嬉しい。行数・列数が一目瞭然である。以下のようなMarkdownでの記法も悪い訳では無いが、どのパイプ文字「|」の内側にいるかを意識しないと、プログラミング言語における括弧閉じ忘れのように、意図しない挙動になりがちだ。 Markdownでの記法 |a |b |c | |---|---|---| |1 |2 |3 | |4 |5 |6 | 3. ルビが振れる Asciidocでの記法 ...

GitHub Flavored Markdown（GFM）とは？ GFMとは何か？ GFM（GitHub Flavored Markdown）は、GitHubが開発・採用しているMarkdownの方言である。。GitHub上でのREADMEやIssue、Wikiなどに使われている形式で、CommonMarkをベースに以下のような拡張機能が加わっている。 CommonMarkでできること・できないこと 以下は、同一のMarkdown文書をCommonMarkとGitHub Flavored Markdown（GFM）でレンダリングした比較画像である。細かな違いが視覚的に理解できる。純粋なCommonMarkと比べて、基本的な整形記法に対応しており、現実的に使える方言として活用できる（純粋なCommonMarkでは表はチェックリストすら未対応）。 GFMでの追加機能一覧 GFMがサポートしている主な機能を以下表に示す。 機能 GFMでの対応 サンプル記法 表（table） ✅ 対応 ` ——– —- 内容1 内容2 ` チェックボックス ✅ 対応 - [x] 済み - [ ] 未完了 行内コード ✅ 対応 コード シンタックスハイライト ✅ 対応 python\nprint("hi")\n 自動リンク（URL） ✅ 対応 https://example.com → 自動リンク 打ち消し線 ✅ 対応 ~~打ち消し~~ → 打ち消し @メンション ✅ 対応 @username SHA, Issue番号 ✅ 対応 #123, deadbeef（リンク化） タスクリスト ✅ 対応 - [ ] task HTMLタグ ✅ 部分対応 セキュリティ上、制限あり 結論：なぜGFMは実用で好まれるのか？ 表やチェックリスト、コードハイライトなど、日常的なドキュメントに便利な機能が揃っている GitHubという大規模なプラットフォームでの利用により、事実上の業界標準となっている Markdownの方言による違いが気になる場合は、より厳密な構造記述が可能な Asciidoc の導入も検討する価値がある。 ...

Markdown方言比較ツールの紹介と公開 なぜこのツールを作ったのか 軽量マークアップ言語であるMarkdownは、記法について覚えることが少なく気軽に書けるため、ちょっとしたメモから、手順書等のドキュメント、スクリプトのREADME.md等を書くのに重宝している。しかし、以下記事で取り上げたように、実はMarkdownには各種方言があり、実行環境によっては特定の記法が使えないなどの落とし穴がある。 Markdown方言の全体像 そこで上記記事では、代表的な方言である、CommonMarkとGitHub Flavored Markdownを取り上げ、以下図のように比較した。この比較画像を作成する際、HTML+JavaScriptにてちょっとした比較ツールを作成したのだが、1回使ってお蔵入りするのも勿体無いと感じたので、ソースコードを公開することにする。 使い方 この比較スクリプトは、Markdownを異なるレンダリングエンジンで表示した結果を並べて比較できる、ローカル実行型のHTMLツールである。 主な表示内容は以下の3つである： Raw Markdown：入力したMarkdownソース Whitespace Annotated：空白・改行を記号で可視化したもの（スペース=␣、改行=↵） CommonMark / GFM Rendering：2つのエンジン（CommonMarkとGitHub Flavored Markdown）による表示結果 1. ファイルの準備 記事内に掲載されたHTMLコードをコピーし、任意のファイル名（例：compare.html）で保存する。 2. 実行方法 保存したHTMLファイルをWebブラウザで開くと、自動的にツールが起動する。 ※このツールはJavaScriptを使用しており、ライブラリをCDN経由で読み込むため、インターネット接続が必要である。 3. 使用手順 左側のテキストエリアに比較したいMarkdown文書を入力する。 入力に応じて、以下の3カラムがリアルタイムに更新される： Whitespace Annotated：スペースと改行を可視化（整形トラブルの特定に有用） CommonMark Rendering：CommonMark仕様による出力 GFM Rendering：GitHub Flavored Markdownによる出力 4. 例 以下のようなMarkdownを入力すると： # 見出し - リスト - ネスト これは~~打ち消し線~~である - [x] 完了 - [ ] 未完了 GFMとCommonMarkの挙動の違い（チェックボックスの描画、打ち消し線の有無など）が視覚的に確認できる。 5. ライセンス MITライセンス 6. 補足事項 ※本ツールでは、JavaScriptライブラリをCDN（jsDelivr）経由で読み込んでいる。信頼性の高いCDNを使用しており、通常の使用においてはセキュリティ上の問題はほぼないが、気になる場合はローカルにライブラリをダウンロードして使用することもできる。 ...

Markdown方言のCommonMarkとは何か？ → Markdown方言の全体像については以下の記事を参照のこと Markdown方言の全体像 CommonMarkとは何か？ CommonMarkは、Markdownの明確な仕様と互換性を持たせることを目的とした標準化プロジェクトである（2014年発足）。このため、これを方言と表現するのは正確では無いが、利用者からすれば、「結局また新たな仕様が派生した」ように見えるので、便宜的に方言として扱う。 曖昧な記法を厳格に定義 公式のテストスイートと仕様書（https://spec.commonmark.org） 実装ごとの差異を減らすことを目指す CommonMarkでできること・できないこと 以下は、同一のMarkdown文書をCommonMarkとGitHub Flavored Markdown（GFM）でレンダリングした比較画像である。細かな違いが視覚的に理解できる。 CommonMarkがサポートしている主な機能と、未対応の機能を以下表に示す。 機能 CommonMarkでの対応 サンプル記法 見出し ✅ 対応 ## 見出し2 段落・改行 ✅ 対応 行末に2スペース / 空行 強調（太字・斜体） ✅ 対応 **太字**, *斜体* リスト ✅ 対応 - アイテム, 1. 番号付き コード ✅ 対応 インライン: code / ブロック: code リンク・画像 ✅ 対応 [Google](https://...) 引用 ✅ 対応 > 引用文 区切り線 ✅ 対応 ---, *** 表 ❌ 非対応 ※構文上は書けてもHTMLには変換されない チェックボックス ❌ 非対応 - [ ] タスク 脚注 ❌ 非対応 [^1] 比較の準備：次回以降の方針 CommonMarkは、Markdownの「共通語」として各方言との比較の基準に使える。 ...

Markdown方言の全体像 本記事を書こうと思ったきっかけ Markdownの記法について調べようとして、いわゆる「記法一覧」記事を参考にすることがある。しかし、それらの多くはどのMarkdown方言を前提にしているのかが明記されておらず、いざ自分の使っている環境で試すと、思ったように表示されない、ということが何度かあった。 おそらく、記事を書いた側も「方言があること」を十分に認識しておらず、自分の使っているツールの仕様を“Markdownの標準”だと誤解しているのかもしれない。 こうした経験から、Markdownには複数の方言があり、それぞれに対応する記法と環境があることを整理し直したいと考え、このシリーズを書くことにした。 はじめに Markdownは「軽量マークアップ言語」として広く使われており、シンプルな記法で文書を整形できることから、ブログ・技術文書・ドキュメント・ノートアプリなどで広く採用されている。しかし、Markdownには正式な標準が長らく存在せず、上述の通り、各ツール・サービスごとに**微妙に異なる記法の“方言（ダイアレクト）”**が存在している。 なぜ方言が生まれたのか Markdownには元々厳密な仕様がなかった（2004年にJohn Gruberが提案したが、仕様書は曖昧） ツールやWebサービスが独自に拡張して便利機能を追加（例：チェックリスト、表、脚注など） この結果、「どのMarkdown環境で、何が書けるのか」が分かりにくくなった 代表的なMarkdown方言と特徴 方言名 主な特徴 CommonMark Markdownの厳密仕様を定義した“標準化”プロジェクト。拡張なし。 GFM（GitHub Flavored Markdown） CommonMarkベースに表・チェックボックス・打ち消し線などの拡張あり Obsidian Markdown CommonMarkベース＋内部リンク、脚注、YAML frontmatter等の拡張 Pandoc Markdown 脚注、数式、フィルターなど高機能・LaTeX出力向け 比較の一例：CommonMark vs GitHub Flavored Markdown 以下がCommonMarkとGitHub Flavored Markdownを比較した結果のスクリーンショットだ。 なお、この検証用に作成した比較ツールは、以下記事で公開している。 Markdown方言比較ツールの紹介と公開 違いが生じた箇所を表にまとめると、以下になる。 表現 CommonMark GitHub Flavored Markdown チェックボックス ❌ 表示されない ✅ <input type="checkbox">に変換される 表 ❌ 表示されない ✅ <table>として表示 打ち消し線 ❌ ~~text~~は無視 ✅ <del>タグとして解釈 このように、書いたMarkdownがどの環境でどう見えるかは“方言”に依存している。 各アプリの採用方言まとめ アプリ・サービス 採用方言 備考 GitHub GFM 表、チェックボックス、打ち消し線に対応 Obsidian Obsidian独自 脚注、内部リンク、YAML frontmatterなど拡張多数 Typora Pandoc風 数式・脚注・LaTeX出力に強い Zenn GFMベース＋独自 @[toc] やKaTeX数式サポートなど Qiita GFMベース＋拡張 TOC・絵文字・Mermaid対応など独自性あり StackEdit GFM互換＋MathJax 表示力が高いWebエディタ 今後の記事構成 本記事は概要まとめとして、次の各記事で以下の方言を詳しく紹介していく予定だ。 ...

Typoraのすすめ .txtから.mdへの転換 私はもともと、仕事でもプライベートでも、メモを残す手段としてテキストファイルを多用していた。世の中にはWordでメモを取る人もいるが、あれはまったく性に合わなかった。Wordファイルはプラットフォームに依存し、ファイルは余計なデータで重く、テキストエディタで開こうとすればバイナリ表示になってしまう。しかもバージョンが違えば互換性も怪しい。 そういった理由から、私は軽くてシンプルなテキストファイルでのメモ運用を続けていた。ただ、やはり文字の強調や階層構造といった、最低限の装飾表現が欲しくなり、テキストエディタでそのまま読めるフォーマットとしてMarkdownにたどり着いた。覚える記法も少なく、すぐに馴染めた。 VS Code重すぎ問題とTyporaとの出会い ところが、Markdownを書くためにVS Codeなどの統合開発環境を使うと、機能が多すぎて書くことに集中できない。2ペイン構成も仰々しく、軽快にメモを取りたい私には合わなかった。テキストエディタに近い感触のMarkdownエディタを探していた時に出会ったのが、Typoraだった。 Typoraは、何よりもそのシンプルさに惹かれた。画面は1ペインで、書いているMarkdownがその場で即座にレンダリングされる。以下の画像からも分かるように、編集画面とプレビュー画面が一体化しており、視線移動やモード切替の必要がない。文書を構造的に書きながら、常に整った見た目を確認できるのが最大の利点だ。 ちなみにCtrl+/を押すと、以下画像のようにレンダリング表示が一時的にオフになり、純粋なMarkdown記法がそのまま見える編集モードになる。構文の確認や、細かな記述の修正をしたいときには便利な機能だ。通常の「書く→見る」の切替と違って、同じペインでモードを切り替えられる点が、Typoraならではの洗練された体験を支えている。 メモだけで終わらない：実用的な文書出力 用途としてはメモが中心だが、それにとどまらない。Markdownでそのまま技術文書やドキュメントを書き、TyporaからPDF・HTML・EPUBなどに美しくエクスポートできるのも魅力だ。見た目も整い、軽量で、実用と美しさが両立する文書を誰でも作れる。PDF出力したサンプルを以下に示す。 📄 PDF出力されたサンプル Typoraは高コスパの買い切り型エディタ Typoraは14.99＄と有料だが、これで永続ライセンスである。今後も妙なエディタでストレスを抱えながら書き続けるくらいなら、この一度の投資で済ませる方が合理的だ。安い。 誰に勧めたいかと問われれば、すべての「文章を書く人」だ。特に、技術文書を書く開発者、知識管理をMarkdownで行う人、日々の記録を手軽に残したい人には強く推せる。 🌐 公式サイト：typora.io シンプルなUIと軽快な動作、そして買い切りライセンス。公式ページから詳細な情報やスクリーンショットも見られるので、気になったらぜひ覗いてみてほしい。 Typoraへの唯一の要望：Asciidoc対応 不満はほとんどないが、強いて言えばMarkdown自体の限界は感じている。Markdownにはプラットフォームごとの方言が多く、また標準機能が貧弱なため、カスタム拡張で乱立しているのが現状だ。その点、Asciidocのようなより強力な記法に興味はあるものの、Typoraのように1ペインで快適に使えるAsciidocエディタがないため、移行をためらっている。TyporaがAsciidocにも対応してくれたら、それが唯一の要望だ。 書くことに集中できる数少ないエディタ 優れた道具は手になじむ。それだけではなく、使っていること自体が誇らしくなる。──Typoraはまさにそんな道具だ。 Typoraは「余計なものがない」ことを美徳としながらも、実用性は非常に高い稀有なツールである。文章を書くこと自体を快適にしてくれるこのエディタは、私の思考と記録の中核に今や欠かせない存在となっている。