オンラインの無料Markdownプレビューア

Markdownチートシート

Markdownについて

Markdown は、Daring Fireball ブログの背後にある作家 John Gruber によって、Aaron Swartz からの実質的な設計フィードバックで作成されました。最初の公開バージョン 1.0 は2004年3月9日に Gruber のサイトで発表されました、バージョン 1.0.1、標準的なリファレンスバージョン、は2004年12月17日に続き、依然として daringfireball.net/projects/markdown からリンクされたバージョンのままです。Markdown は同時に 2 つのものです:プレーンテキストのフォーマット構文、その構文を HTML に変換する元の Perl スクリプト。Gruber の宣言された目標は、ソーステキストがそのまま読める、つまりプレーンテキストエディタで開かれた Markdown ドキュメントが、タグスープではなく注意深くフォーマットされたメールのように見えるべきであることでした。この読みやすさ制約は Markdown を XML ベースのフォーマットや LaTeX のような重い markup から分離する哲学的なラインで、それが各後続の拡張がソースをどれくらい妨害するかの観点で正当化されなければならない理由です。

Gruber は Markdown の謝辞で Swartz を長くクレジットします:「Aaron Swartz は Markdown のフォーマット構文の設計に対するフィードバックで多くの功績を持つ」。Swartz は以前 atx(2002)と呼ばれる関連する軽量 markup を書きました、これは現在馴染みのある # と ## 見出しスタイル、時にはパーサー仕様で「atx スタイル見出し」と呼ばれる、に貢献しました。Swartz の関与は彼のより広い遺産の一部です:彼は 10 代で RSS 1.0 を共同構築し、2007 年まで Reddit の共同所有者で、2013 年の彼の死まで Open Web 標準に影響を与え続けました。心に留めておくべきトリビア:ファイル拡張子 .md は今や事実上普遍的ですが、Gruber の元のツールは .text を使用していました、.md への移行は Markdown がブログニッチを離れたときに普及したコミュニティ慣習でした。

なぜ Markdown は Web を勝ち取ったか

markup 言語は世界のテキストの大部分を公開するプラットフォームに採用されることで勝ちます。タイトな 5 年ウィンドウで、Markdown は長文ディスカッション、コード共同作業、開発者ドキュメントを支配するに至るプラットフォームに採用されました。Stack Overflow は2008年9月15日にローンチし、John Fraser of AttackLab による WMD(Wysiwym Markdown)というエディタを使用して、質問、回答、コメントのフォーマット構文として Markdown を持ちました、Stack Overflow チームは後にそれを github.com/StackExchange/pagedown でメンテナンスされるオープンソース PageDown エディタとして書き直しました。Reddit、2005 年に Steve Huffman と Alexis Ohanian によって設立され、Aaron Swartz がすぐ後に参加、はローンチ後すぐにコメントに Markdown を出荷し、構文をはるかに広い非開発者の聴衆に運びました。GitHub は 2008 年にローンチし、1 年以内に README.md とイシューコメントで Markdown をレンダリングしていました、2009 年に独自の方言、GitHub Flavored Markdown を文書化し出荷し始めました。Discord、2015 年 5 月にローンチ、はチャットの太字、斜体、取り消し線、インラインコード、コードブロック、ブロッククォートに Markdown 風の構文を採用しました、25 歳未満のほとんどの非開発者が今や「何かの周りに星を置く」と呼ぶもの。スキルは累積します:Markdown を一度学んだ作者は、Jekyll/Hugo/Eleventy でブログ投稿を書け、MkDocs/Docusaurus/Read the Docs でドキュメントを書け、Marp と Reveal.js でプレゼンテーションを書け、Obsidian/Bear/Logseq/Notion でノートを書け、Slack と Discord でチャットを書け、ほぼあらゆる現代のオープンソースプロジェクトでソースコードドキュメントを書けます。

CommonMark、未仕様化を修正

Gruber の2004年の元の構文記述は有名にカジュアルでした、文法ではなく例を持つ散文ドキュメント。それは数十のエッジケース(「emphasis は単語の途中のアンダースコアとどう相互作用するか?」、「ブロッククォート内のリストはブロッククォートを閉じるか?」、「タイトリストとルーズリストとして何が数えるか?」)を未指定のままにし、Gruber は彼の Perl スクリプト以外のリファレンスパーサーを公開しませんでした、その動作は他の実装者がコピーするかオーバーライドするかしなければならなかった方法で特異でした。2010 年代初頭の結果は、GitHub、Reddit、Stack Overflow、Pandoc、C パーサー Discount がすべて同じ Markdown ソースをわずかに異なるようにレンダリングし、同じ入力がプラットフォーム間で壊れる可能性があったことです。

2012 年、Stack Overflow 共同創業者 Jeff Atwood(当時 Discourse をリード)と Pandoc 著者 John MacFarlane は実際のテスト可能な仕様を書く努力を始めました。彼らに David Greenspan(Meteor)、Vicent Marti(GitHub)、Neil Williams(Reddit)、Benjamin Dumke-von der Ehe(Stack Exchange)が加わりました。プロジェクトは2014年9月に「Standard Markdown」として公的にローンチしました、数日以内に、Gruber はプライベートメールで名前に異議を唱え、Atwood は変更を説明する公開投稿を書き、プロジェクトは「CommonMark」に名前変更されました。最初の番号付きリリースは2014年10月25日に到来しました。現在公開されているバージョンは2024年1月28日にリリースされた CommonMark 0.31.2 です、2019 年に「1.0」が約束され到来しませんでした、少数の病的なエッジケース(特に emphasis 解析と HTML 埋め込みの周り)が満場一致の解決を生み出さなかったからです。実際には、0.31.2 は本番のために安定として扱われます。CommonMark 仕様はそれ自体が CommonMark ドキュメントであり、600 以上の実行可能なテストケースをオンラインで持つ点で異常です、パーサーはそれらのテストを通過することで準拠を主張します。

GitHub Flavored Markdown、その上の 5 つの拡張

正式な GFM 仕様、2017 年に公開され、2019 年 4 月 6 日に最近 0.29-gfm としてバージョン管理、は CommonMark の上の 5 つの拡張を定義します:テーブル(列ごとの整列のためにダッシュと : を使用する区切り行を持つパイプ区切りブロック)、タスクリストアイテム(チェックされていないなら [ ]、チェックされているなら [x] で始まるリストエントリ、無効な HTML チェックボックスとしてレンダリング、GitHub はさらにログインしたユーザーがクリックでそれらをトグルすることを許可、これは仕様の一部ではなく仕様の上の UX レイヤー)、取り消し線(~~ でテキストをラップすると <del> を生成、CommonMark 自体はこれを指定しない)、autolinks 拡張(実行テキストの裸の URL とメールアドレスは自動リンクされる、CommonMark は明示的な角括弧 autolinks のみそれを行う)、raw HTML 禁止(<script>、<iframe>、<style>、<title>、<plaintext>、<textarea>、<xmp>、<noembed>、<noframes>、その他いくつかの危険なタグを除去するセキュリティ制限)。GFM に一般的に帰されるが慎重な扱いに値する 6 番目の機能は言語識別子付きフェンスコードブロックです、フェンスコードブロックは CommonMark 自体の一部、開きフェンス後の言語ヒントも CommonMark、その後 GitHub がそのヒントに基づいて適用するシンタックスハイライトは仕様ではなく GitHub のレンダリング動作です。GitHub のレンダリングエンジンはまた追加の後処理を実行します、ハウス gem html-pipeline を介した HTML サニタイゼーション、絵文字ショートコード展開(:smile:)、@user と #issue autolinking、いずれも GFM 自体の一部ではありません。

主要なパーサー

marked.js は Christopher Jeffrey によって作成され、元の著作権は2011年付け、2018 年から GitHub markedjs 組織によってメンテナンスされています。それは生のスピードを優先する 1 パスのレクサー-then-パーサー設計です、ドキュメントはそれを「キャッシュやブロックなしで markdown を解析する低レベルコンパイラ」として明示的に位置付けています。これはこのプレビュアーがライブレンダリングのために現在使用するパーサーです。Marked は小さく、高速で、トークンフックを介して拡張可能で、GitHub で最も星の付いた markdown プロジェクトの 1 つ(~36k 星)です。

markdown-it は2014年に Vitaly Puzrin と Alex Kocharin によってローンチされました。両者は以前 Remarkable と呼ばれるパーサーにほぼすべてのコードを貢献していました、リーダーシップ紛争が進歩をブロックしたとき、彼らは markdown-it 周りに同じ著者を再編成しました。プロジェクトはテーブルと取り消し線のオプションの GFM トグルで 100 % CommonMark 準拠を宣伝し、加えて積極的なプラグインエコシステム(markdown-it-footnote、markdown-it-emoji、markdown-it-attrs、markdown-it-anchor、markdown-it-task-lists、その他数百)。これは VS Code の組み込み Markdown プレビュー、GitLab の Web UI、Eleventy を含む静的サイトジェネレーターの長いリストで使用されるパーサーです。

remark / unified.js は単一のパーサーではなく、ツリー変換フレームワークです。unified コレクティブ、約2014年に始まった、は mdast(Markdown Abstract Syntax Tree)と呼ばれる抽象構文木仕様を定義します、remark は Markdown を mdast に解析、プラグインがツリーを操作、remark-rehype が mdast を出力のために hast(HTML AST)に変換します。モデルは marked より遅いですが、はるかに構成可能です。注目すべきユーザーには Prettier(remark で Markdown をフォーマット)、Gatsby、MDN、Node.js のドキュメントパイプライン、包括的言語リンター alex が含まれます。unified コレクティブは 312 プロジェクトと、すべてのパッケージにわたって月約 63 億の npm ダウンロードをリストします。

MDX、デザインツール会社 Compositor に接続された John Otander らによって2017年後半に最初にコミット、は2018年の ZEIT Day で公的に発表され、2019年4月11日に 1.0 を出荷しました。MDX は Markdown コンテンツを JSX コンポーネントと組み合わせます、つまり著者は <Chart /> や <Tweet id="123" /> を散文に直接ドロップできます。それは Next.js ドキュメント、Docusaurus、ほとんどの React ベースのドキュメントサイトを動かします。MDX は CommonMark とは別の独自のパーサーを持ちます、v1 は remark ベースでしたが、v2+ は段落コンテキスト内の JSX 式を正しく処理する専用 MDX 文法を使用します。

Pandoc、普遍的な変換器

Pandoc は2006年8月10日に当時カリフォルニア大学バークレー校の哲学教授だった John MacFarlane によって公開されました。それは Haskell で書かれており、その設計は約 30 の入力フォーマット(Markdown、reStructuredText、HTML、LaTeX、DocBook、Textile、MediaWiki と DokuWiki markup、Org-mode、Microsoft Word .docx、OpenDocument、EPUB、JATS XML、Jupyter .ipynb など)のうちの 1 つを共有された抽象ドキュメントモデルに解析し、それからそのモデルを約 40 の出力フォーマット(HTML、LaTeX 経由または wkhtmltopdf 経由の PDF、.docx、.odt、ePub2/3、Beamer と reveal.js を含むスライドフォーマット、その他多数)にレンダリングすることに集中します。それは CSL JSON / BibTeX を介して引用を運び、それらを主要な引用スタイルのいずれかにフォーマットされた参照に解決するので、学術および技術出版で普遍的です。Pandoc がデフォルトで解析する Markdown 方言(「Pandoc Markdown」)はそれ自体が脚注、定義リスト、フェンス div、数学(LaTeX 風の $...$ と $$...$$)、テーブルキャプションのための拡張を持つ CommonMark スーパーセットです。Pandoc は GPL v2-or-later でライセンスされ、ほとんどの学術部門が Markdown 原稿を公開準備の Word ドキュメントにコンパイルするために使用するものです。

MultiMarkdown、Markdown Extra、SmartyPants

CommonMark に先行し GFM と Pandoc の両方に影響を与えた 2 つの初期の拡張方言。MultiMarkdown は Fletcher T. Penney によって作成され、最初のリリースは2007年5月(プロジェクト作業は2005-2006年に始まりました)、学術ライティングによって動機付けられました、Penney は脚注、引用、数学、定義リスト、YAML 風のドキュメントメタデータで公開可能な原稿を生成できる Markdown を望んだ。MultiMarkdown はパイプテーブル、脚注マーカー [^id]、数学記法、ファイル先頭のドキュメントレベルメタデータブロック、画像とテーブルキャプションを導入または普及させました。Markdown Extra は2005-2006年に Michel Fortin(PHP Markdown の著者)によって作成され、パイプテーブル、~~~ でのフェンスコードブロック(後に ``` も)、脚注、定義リスト、略語、見出しの属性構文 {#id .class} を追加しました。その最も独特な貢献は Markdown-in-HTML ルールの緩和でした、HTML ブロック内に Markdown をネストできる markdown="1" 属性。フェンスコードとテーブル周りのいくつかの CommonMark と GFM 設計選択は Markdown Extra にさかのぼります。別に、SmartyPants、Gruber 自身の2002年のタイポグラフィー仲間、はタイポグラフィー置換を実行します:ストレート ASCII 引用符は曲線引用符になり、ダブルとトリプルダッシュは en と em ダッシュになり、3 つのドットは適切な省略記号になります。Markdown は構造を扱う、SmartyPants は磨きを扱う、多くのパーサーは SmartyPants 風の動作を後処理ステップ(markdown-it-smartypants、remark-smartypants)としてバンドルし、Pandoc は --smart フラグの背後でそれを統合しました。

一般的な落とし穴、新しい著者を噛む 10 のこと

ライブプレビュアーはほとんどのパース驚きを即座に明白にしますが、なぜそれらが起こるかを理解することは、著者が最初に正しいソースを取得するのを助けます。

1. コード例を壊すスマートクォート変換。 SmartyPants 風のフィルターは散文に見えるものの引用符を喜んで変換します、時にはインラインコードスパンや HTML 属性値の内部を含み、壊れた markup を残します。ほとんどの現代のパーサーはタイポグラフィー置換からコードスパンを除外しますが、カスタムパイプラインを持つブログプラットフォームはしばしばそうしません。
2. リストマーカー検出は空白に敏感です。 同じリスト内で -、*、+ を混在させる、リスト継続段落をマーカーが要求するより少なくインデントする、またはリストアイテム間に空行を置くことは、タイトリスト(各アイテムが <p> タグでラップ)からルーズリストに切り替える可能性、ソースで見えない違いだが出力で劇的。
3. Autolink の過剰な熱意。 GFM 風の autolinking は裸の URL をリンクに変えます、それは通常望むことです、しかしコードスパンであるべきものの中の URL や、括弧を含む URL(特に Wikipedia URL)を破壊する可能性もあります。「この URL はどこで終わるか?」のルールはパーサー間で変動します。
4. コードフェンス言語ヒント。 開き三重バッククォート後のテキスト、```js vs ```javascript vs ```ts vs ```typescript、はヒントで、仕様ではありません。異なるシンタックスハイライターは異なるエイリアスを認識します、Highlight.js、Prism、Shiki、GitHub のレンダリングエンジンはそれぞれ独自の言語辞書を持ちます。
5. エスケープを必要とするテーブル。 テーブルセル内のパイプ文字は \| としてエスケープされなければなりません、そうでないと列セパレータとして読まれます。テーブルセル内に 1 行のコード例を入れようとする人を捕まえます。
6. ハード改行。 段落内では、単一の改行は空白として扱われ、行は結合されます、行末に 2 つのスペースを置く必要があるか、バックスラッシュを使用する必要があります、パーサーによって。CommonMark は両方を許可します。一部の古いパーサーは明示的な <br> を要求します。
7. Markdown と HTML を混在させる。 Markdown は任意の HTML を通すように設計されました、Markdown ファイルに <div class="callout"> をドロップするのは機能します。しかし HTML ブロック内に Markdown 構文を置くとすぐに、パーサーは分岐します:CommonMark はほとんどの HTML ブロックを不透明として扱う、Markdown Extra はネストされた解析を有効にする markdown="1" を導入。
8. HTML エンティティと文字エスケープ。 URL 内のアンパサンド & は Markdown リンク内ではエスケープを必要としませんが、リンク外の同じ & は HTML に渡され、厳密な HTML5 準拠のために & である必要があるかもしれません。ほとんどのレンダラーはこれを自動的に処理します、一部はそうしません。
9. 見出し ID。 GitHub は slugify ルールを使用して見出しテキストから URL フラグメント ID を自動生成します、多くのパーサーが同じことをしますが、slugify アルゴリズムは異なります。同じ見出し、プラットフォーム間で異なるアンカー、コンテンツがシステム間で移動するときの壊れたドキュメント内リンクの永続的な原因。
10. 末尾スペースとエディタ設定。 保存時に末尾スペースを除去するエディタは Markdown の 2 末尾スペース改行構文を静かに削除します。タブをスペースに(または逆に)変換するエディタはインデントに依存するコードブロックを壊します。

Markdown とセキュリティ、XSS とサニタイゼーション

Markdown は特定の方法で危険です:すべての主流パーサーは生の HTML を変更なしに通します。それは設計によるもの、それが Markdown を手作業のコールアウトと埋め込みに有用にすることです、しかしそれはまた DOM にパーサー出力を直接注入する Markdown プレビュアーがデフォルトで XSS ベクトルであることを意味します。Markdown エディタに <img src=x onerror="alert(1)"> を貼り付け、サニタイゼーションなしに出力をレンダリングすると、アラートが実行されます。2 つの防御層が標準です。第一に、パーサーレベル設定:marked.js、markdown-it、remark はすべて生の HTML を無効にするか出力でエスケープするオプションを公開します(markdown-it はデフォルトで html: false、remark/rehype は rehype-sanitize を持つ)。GFM はさらに危険要素のハードコードされたリストを除去する「raw HTML 禁止」拡張を指定します。第二に、より堅牢、解析後 HTML サニタイゼーション:DOMPurify、ベルリンセキュリティ会社 Cure53 が2014年2月から書いた、は事実上の JavaScript サニタイザーです。それは HTML 文字列を取り、DOM に解析し、安全で設定可能なサブセットの要素と属性のみを許可してツリーをトラバースし、結果をシリアル化します。DOMPurify は <script> を除去し、インラインイベントハンドラーをブロック、javascript: URL を除去、ナイーブな regex サニタイザーが見逃す数十の微妙な XSS バイパス(SVG <use> 悪用、MathML 属性ポリグロット)を処理します。生の HTML を受け入れるブラウザベースのプレビュアーの推奨パイプラインは:markdownString → parser → htmlString → DOMPurify.sanitize() → innerHTML。CommonMark はまた明示的にパーサーが autolinks 内の javascript: URI を拒否することを要求します、ほとんどのパーサーは拒否をすべてのリンク形式に拡張します。

Markdown vs reStructuredText vs AsciiDoc

Markdown は支配的な軽量 markup 言語ですが唯一ではありません。reStructuredText(reST)は2001年6月に Python Doc-SIG の一部として David Goodger によって最初に公開され、StructuredText と呼ばれる以前の Zope フォーマットから進化しました。それは2002年に Python の公式ドキュメンテーションフォーマットになり、Sphinx の入力言語です、ほぼすべての Python プロジェクトドキュメント(公式 Python 言語ドキュメント、NumPy、SciPy、Django、Flask、scikit-learn、pandas、2016 年からの Linux カーネルドキュメンテーション、CMake、LLVM)の背後にあるドキュメントジェネレータ。RST の設計哲学は本質的に Markdown の反対です:出力でより多くの意味的精度を交換するために、ソースでより多くの視覚的ノイズを受け入れます。RST は「ディレクティブ」(.. note::、.. code-block:: python)と「ロール」(:func:、:ref:)を介して組み込み拡張メカニズムを持ちます、フォーマットを離れずにプロジェクトがドメイン固有の markup を定義することを許します。AsciiDoc は2002 年に Stuart Rackham によって意図的に DocBook XML セマンティクスをターゲットとする Python ツールとして作成されました、すべての AsciiDoc ドキュメントは DocBook にきれいにマップします、出版品質の本、技術仕様、マニュアルを必要とするプロジェクトのための markup 選択にしました。AsciiDoc は Git プロジェクトドキュメントが書かれているもの、O'Reilly Media が多くの本に使用するもの、Red Hat と Mozilla が複数の製品ドキュメントセットに使用するもの、GitHub と GitLab が README.adoc の代替としてネイティブにサポートするものです。元の Python 実装は 2013 年に公開された Ruby 実装の Asciidoctor によって置き換えられました。実用的なアドバイス:ブログ投稿、README、チャット、ノート、ほとんどのドキュメントには Markdown を選んでください、Sphinx 経由で処理される Python ドキュメントには reStructuredText、完全な意味的忠実性で同時に DocBook、PDF、EPUB にレンダリングする必要がある本や長い仕様には AsciiDoc を選んでください。

よくある質問

どのMarkdown機能がサポートされていますか？

このプレビューアは、見出し、太字、斜体、リンク、画像、リスト、引用ブロック、コードブロック、表、水平線、取り消し線をサポートしています。CommonMark仕様と一般的な拡張をカバーしています。

レンダリングされたHTMLをエクスポートできますか？

プレビューパネルからレンダリングされた出力をコピーできます。生のHTMLについては、プレビューを右クリックしてブラウザの「検証」または「ソースを表示」機能を使用し、生成されたマークアップをコピーしてください。

私のテキストは保存されますか？

いいえ。すべてはブラウザ内で実行され、サーバーには何も保存も送信もされません。タブを閉じるとテキストは消えます。保存したい場合は離れる前にMarkdownをコピーしてください。

私のテキストは保存またはどこかに送信されますか?

いいえ。Markdown パーサーは JavaScript を介してブラウザで完全に実行されます。何もアップロードされず、API は呼ばれず、ログは書かれません。タブを閉じるとテキストは消えます。書いたものを保持したい場合は、ページを離れる前にコピーしてください。ロード後にページをオフラインで使用することもできます、サービスワーカーキャッシングはインターネット接続なしでパーサーが利用可能のままであることを意味します。

プレビュアーは生の HTML をサニタイズしますか?

パーサーは生の HTML を通します、それは標準の CommonMark 動作です、たまの <div> や <details> を埋め込むのに有用。入力があなた自身のブラウザセッションから来て、出力があなた自身のタブでのみレンダリングされるので、それは構築された 1 人プレビューのユースケースに安全です。出力をマルチユーザーシステム(CMS、フォーラム、ユーザー投稿を受け入れるドキュメントサイト)に公開する場合は、レンダリングされた HTML を公開ページに注入する前に DOMPurify のようなサニタイザーを通すべきです、Markdown プラス生の HTML は著者と読者が異なる人であるあらゆるシステムで XSS ベクトルです。

ファイルサイズ制限はありますか?

ハードな制限はありません。パーサーは典型的なラップトップで問題なく Markdown の数万行を処理します。ライブ再レンダリングはキーストロークごとに実行されるので、非常に大きなドキュメント(単一ファイルの本全体)は遅いデバイスで遅く感じ始めます。章に分割するか、コンテンツを貼り付けて一度レンダリングしてからオフラインで編集することが回避策です。ページはブラウザをフリーズさせません、marked.js は利用可能な最も高速な Markdown パーサーの 1 つです。

関連ツール