マークダウンからHTMLへの変換

仕組み

1. Markdownを貼り付け: 見出し、段落、リスト、コードブロック、テーブル、引用、リンクなど、任意のMarkdownテキストを入力します。
2. 変換: ツールはMarkdownを解析し、要素の適切なネスト付きでクリーンでセマンティックなHTMLを生成します。
3. プレビューまたはコピー: レンダリングをプレビューするか、CMS、ウェブサイト、メールテンプレートに貼り付けるために生のHTMLをコピーします。

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のような重いマークアップから分離する哲学的なラインであり、後のすべての拡張がソースをどれだけ妨げるかという観点で自分自身を主張しなければならなかった理由です。Aaron Swartzは以前に、atx(2002)と呼ばれる関連する軽量マークアップを書いており、これは今でも親しまれている#と##の見出しスタイルに貢献し、パーサー仕様の中で今でも「atxスタイル見出し」と呼ばれることがあります。

CommonMark、未仕様化の修正

Gruberの2004年のオリジナルの構文記述は有名に非公式で、例を含む散文文書であり、文法ではありませんでした。それは数十のエッジケースを未仕様のままにし、Gruberは彼のPerlスクリプト以外のリファレンスパーサーをリリースせず、その動作は他の実装者がコピーまたはオーバーライドしなければならない方法で特異でした。2010年代初頭までの結果は、GitHub、Reddit、Stack Overflow、PandocとDiscount Cパーサーがすべて同じMarkdownソースを少し異なるようにレンダリングしていたことです。2012年、Stack Overflowの共同創設者Jeff AtwoodとPandocの作者John MacFarlaneは、実際の、テスト可能な仕様を書く取り組みを始めました。プロジェクトは2014年9月に「Standard Markdown」として公に開始されました; 数日以内にGruberはプライベートメールで名前に異議を唱え、Atwoodは変更を説明する公開投稿を書き、プロジェクトは「CommonMark」に改名されました。最初の番号付きリリースは2014年10月25日に来ました。現在の公開バージョンは2024年1月28日にリリースされたCommonMark 0.31.2です。CommonMark仕様は、それ自体がCommonMarkドキュメントであり、600以上の実行可能なテストケースがインラインに含まれている点で珍しいです; パーサーはそれらのテストに合格することで適合性を主張します。GitHub Flavored Markdown (GFM)、バージョン0.29-gfm 2019年4月6日付の正式仕様は、CommonMarkの上に5つの拡張を定義します: テーブル、タスクリストアイテム、ストライクスルー、ベアURLのオートリンク、および許可されない生HTML(著者提供のHTMLから危険なタグを取り除くセキュリティ制限)。

主要なパーサー

marked.jsは2011年にChristopher Jeffreyによって作成され、2018年以来markedjs GitHub組織によって維持されています。単一パス、レクサー-then-パーサー設計で、生の速度を優先します; 〜36kのスターを持ち、GitHubで最もスターを獲得しているMarkdownプロジェクトです。これはこのツールが変換に使用するパーサーです。markdown-itは2014年にVitaly PuzrinとAlex Kocharinによって立ち上げられ、CommonMarkへの100%適合と、オプションのGFMトグルに加えて、攻撃的なプラグインエコシステム(markdown-it-footnote、markdown-it-emoji、markdown-it-attrs、markdown-it-anchorと数百の他のもの)を宣伝しています。VS Codeの組み込みMarkdownプレビュー、GitLabのWeb UI、Eleventyで使用されるパーサーです。remark / unified.jsは単一のパーサーではなく、ツリー変換フレームワークです、unified collectiveはmdast(Markdown AST)と呼ばれる抽象構文木仕様を定義します; remarkはMarkdownをmdastに解析し、プラグインがツリーを操作し、remark-rehypeはmdastをhast(HTML AST)に変換して出力します。markedより遅いですが、はるかに構成可能です; 注目すべきユーザーにはPrettier、Gatsby、MDN、およびalex inclusive-language linterが含まれます。PandocはJohn MacFarlaneによって2006年8月10日にリリースされ、ユニバーサルドキュメントコンバーターで、Haskellで書かれており、約30の入力フォーマットを解析し、約40の出力フォーマットにレンダリングします; 学術的および技術的出版に普及しています。

MD-to-HTMLパイプライン、機械的に

Markdownパーサーは通常2パスで動作します。ブロックレベルパースは入力をブロック構造に分割します、段落、見出し、リスト、コードフェンス、ブロッククォート、水平線、テーブル。ブロック境界は空白行とインデントによって決定されます; それらを正しく行うことがCommonMarkパーサーを正しくすることのほとんどです。インラインパースは次に各ブロックの内容を歩き、インライン構文に一致します: 強調(*italic*、**bold**)、リンク([text](url))、インラインコードスパン(`code`)、画像(![alt](url))、ストライクスルー(GFMの~~text~~)、および明示的なオートリンク(<https://example.com>)。インライン強調パースはMarkdown仕様の中で最も厄介な部分で、CommonMarkは*foo*bar*が<em>foo</em>bar*と*foo<em>bar</em>のどちらを生成すべきかを指定する仕様の数ページと数十のテストケースを捧げています。パーサーは次に各トークンを対応するHTML要素としてレンダリングし、結果を連結します。プリティプリント、インデント、およびコードブロックのシンタックスハイライトは、レンダリングオプションによって上に積み重ねられます。

そもそもなぜMDをHTMLに変換するのか?

• CMSインポート。 多くのヘッドレスCMS(Contentful、Sanity、Wagtail、Ghost)はHTMLを受け入れますがMarkdownは受け入れません。Markdownでドラフトを作成し、公開時に一度変換することで、編集エクスペリエンスを快適に保ちます。
• メール作成。 メールクライアントはHTMLをレンダリングします; ほとんどはMarkdownをレンダリングしません。ニュースレタープラットフォーム(Mailchimp、ConvertKit、Substack)は通常、エディターに貼り付けられたHTMLを受け入れます。ドラフトを変換、貼り付け、送信します。
• ブログ投稿ドラフト。 Markdownプラグインのない一部のレガシーWordPressインストールは、投稿本文にHTMLを必要とします; 一部のShopifyとWebflowのショップページはrich-textフィールドでHTMLを受け取ります。
• 静的サイトジェネレータースニペット。 HugoショートコードのインラインHTMLチャンク、Eleventyテンプレート、またはNext.js MDXファイルが必要な場合、Markdownを単一のHTML断片に変換することは、SSG自身の変換パイプラインと戦うよりも速いです。
• レンダリングされたノートの共有。 「レンダリングされた」MarkdownをSlack、Notion、Linear、ClickUpまたは他のリッチテキスト宛先に貼り付けると、生のMarkdownではなくクリップボードにHTMLが欲しくなることがあります。
• ドキュメンテーションのアーカイブ。 レンダリングされたHTMLをMarkdownソースと一緒に保存することは、あなたのアーカイブがパーサーなしのブラウザで人間が読めることを意味し、長期保存に役立ちます。

知っておく価値のある出力オプション

異なる下流の使用は変換されたHTMLから異なるものを欲します。完全なドキュメント対フラグメント。 完全なHTMLドキュメントには<!DOCTYPE html>、<html>、メタデータを含む<head>、および<body>ラッパーが含まれており、ファイルを.htmlとして保存しブラウザで開くときに適切です。フラグメントは本文の内容のみで、ラッパーはなく、ドキュメント構造を既に提供するCMSフィールドに貼り付けるときに適切です。このツールはデフォルトでフラグメントを発行します; 完全なドキュメントが必要な場合は独自のboilerplateで包んでください。サニタイゼーション。 デフォルトでMarkdownパーサーは生のHTMLを変更せずに通過させるので、ソースに<script>alert(1)</script>が含まれている場合、そのスクリプトタグは出力に現れます。マルチユーザーシステムに入るドキュメントの場合、DOMに注入する前にDOMPurify(Cure53、2014年2月開始)を介して出力を実行してください。ワンショットの個人使用には、生の出力で問題ありません。ヘッダーID。 見出しにid属性を生成すること(見出しテキストからスラグ化)で、アンカーリンクのある目次を構築できます。正確なスラッグアルゴリズムはプラットフォーム間で異なります、GitHubは1つのルールを使用し、MkDocsは別のルール、marked.jsは3つ目を使用するので、コンテンツがシステム間を移動するときにアンカーリンクが壊れる可能性があります。ハードラインブレイク。 CommonMarkは<br>を強制するために行末の2つの末尾スペースまたはバックスラッシュを必要とします; 一部のプラットフォーム(Discord、GitHub issues)は単一の改行をブレイクとして扱います。選択はソースの期待されるスタイルに依存します。

一般的な落とし穴

• スマートクォート変換。 一部のパーサー(またはGruber自身のSmartyPantsのような後処理レイヤー)はデフォルトでストレートクォートをカーリーなタイポグラフィックなクォートに置き換えます。ストレートクォートを保持する必要がある場合(出力がコードとして解析されているため)、この変換がオフであることを確認してください。
• リストマーカーの空白感度。 同じリストで-と*と+を混在させること、リスト継続段落をマーカーが必要とするより少なくインデントすること、またはリストアイテム間に空白行を入れることは、緊密なリストを緩いリスト(各アイテムが<p>タグで包まれた)に反転させることができます。出力の視覚的な違いは劇的です。
• オートリンクの過度な熱心さ。 GFMスタイルのオートリンクは任意のベアURLをリンクに変えます、これは通常望むことですが、括弧(特にWikipediaのURL)または末尾の句読点を含むURLを台無しにする可能性があります。
• エスケープが必要なテーブル。 テーブルセル内のパイプ文字は\|としてエスケープする必要があります、そうでなければ列セパレータとして読まれます。セル内に1行のコード例を入れようとする誰でも捕まえます。
• MarkdownとHTMLの混合。 Markdownは任意のHTMLを通過させるように設計されているので、Markdownファイルに<div class="callout">をドロップすることは機能します。しかし、HTMLブロック内にMarkdown構文を入れた瞬間、パーサーは分岐します: CommonMarkはほとんどのHTMLブロックを不透明として扱います; Markdown Extraはネストされたパースにオプトインするためにmarkdown="1"を導入しました。
• プラットフォーム間の見出しID。 異なるslugifyアルゴリズムは同じ見出しに対して異なるアンカーフラグメントを生成します; ドキュメント内リンクはコンテンツがシステム間を移動するときに壊れる可能性があります。

このツール対Markdown Previewer

Absolutoolは同じパーサーを共有する2つの関連ツールを出荷します。Markdown Previewerはライブ編集用で、左にMarkdownを書き、右にレンダリングされたビジュアル出力を見ます、「HTML出力」の概念はありません。このMarkdown-to-HTML Converterはワンショット変換用です、Markdownを貼り付け、生のHTMLをコピーし、CMSまたはメールクライアントに貼り付けます。ドラフトを作成して視覚的フィードバックが必要なときはプレビューアを使用してください; 完成したMarkdownがあり、他の場所に運搬できるHTMLが必要なときはこのコンバーターを使用してください。両方のツールは内部でmarked.jsを使用し、同じCommonMark + GFM方言を受け入れるので、それらの間で変換動作は同一です。

プライバシー: なぜブラウザのみがここで重要なのか

未公開の執筆物のドラフト、進行中のブログ投稿、内部ドキュメンテーション、NDAの下のクライアント納品物、原稿の章、学術論文は、まさにサードパーティサービスにアップロードしたくない種類のテキストです。サーバーサイドのMarkdownコンバーターは、ドキュメント全体をリモートエンドポイントに送信することを必要とし、それはサーバーのログ、おそらくCDNキャッシュ、おそらく分析パイプライン、おそらくバックアップに残ることを意味します。公開されたテキストの場合、問題は無意味です。ドラフト作業の場合、アーキテクチャが重要です。このツールはJavaScriptとmarked.js経由でブラウザ内で全パイプラインを実行します。Markdownは決してネットワークを越えません、入力する間にDevToolsのネットワークタブで検証するか、ロード後にページをオフラインに(機内モードに)してコンバーターがまだ機能することを確認してください。機密のドラフト、クライアント納品物、NDAの下の原稿の章、内部メモまたは見知らぬ人のハードドライブにコピーされたくないものに安全です。

よくある質問

このコンバーターはどのMarkdown方言をサポートしていますか?

CommonMarkに最も一般的なGFM拡張が有効になったもの、テーブル(オプションの:整列のあるパイプ区切り)、言語ヒント付きのフェンスされたコードブロック、~~text~~経由のストライクスルー、ベアURLのオートリンク、および[ ]と[x]経由のタスクリストアイテム。見出し、太字、斜体、リンク、画像、リスト、ブロッククォート、水平線、およびインラインコードはすべてGitHubで期待するように機能します。レンダラーはmarked.jsで、Markdown Previewerが使用するのと同じパーサーです。

GitHub Flavored Markdown(GFM)をサポートしていますか?

はい、パイプ付きテーブル、言語ヒント付きのフェンスされたコードブロック、タスクリスト、オートリンク、ストライクスルーすべてが機能します。GFM拡張がレンダリングされていない場合、入力がCommonMark/GFMの構文ルールに従っているかを再確認してください: ブロック要素の周りの空白行、フェンスされたコードブロックのマッチするバックティック数、ハードラインブレイクのためのちょうど2つの末尾スペース(またはバックスラッシュ)。「GFMが機能しない」の最も一般的な原因は、保存時に末尾の空白を取り除くエディタで、これがハードブレイク構文を殺します。

出力はGitHubで同じように見えますか?

構造的HTML、段落、リスト、テーブル、見出しは、有効なCommonMark + GFMの任意の入力に対して一致します。2つのレイヤーが異なります。GitHubは独自のCSSテーマとシンタックスハイライトを適用するので、色、フォント、間隔は異なって見えます。GitHubは仕様の上にも後処理を重ねます、絵文字ショートコード(:smile:)、@userメンション、#issue自動リンク、リポジトリ相対画像パス、これらをスペック準拠のコンバーターは再現しません。このツールが発行するHTMLは構造的に移植可能です; 視覚的な外観は宛先のCSSに依存します。

公開前に出力をサニタイズすべきですか?

ソースがユーザー提供のコンテンツを含む可能性がある場合、はい。Markdownパーサーは生のHTMLを変更せずに通過させるので、<img src=x onerror="alert(1)">を含むソースは出力にそのタグを生成します。マルチユーザーシステムの場合、DOMに注入する前にDOMPurify(Cure53、2014年2月、デファクトのJavaScriptサニタイザー)を介して出力を実行してください。ソースが自分の執筆であるワンショットの個人使用には、これは問題ではありません、自分のページにできる最悪のことは自分のHTMLを貼り付けることです。

headとbodyを持つ完全なHTMLドキュメントを取得できますか?

現在このツールは本文フラグメントのみを発行します、変換されたMarkdownはセマンティックHTMLタグで包まれていますが、完全な<html>/<head>/<body>ドキュメントではありません。スタンドアロン.htmlファイルとして保存するには、出力を自分で包んでください: <!DOCTYPE html><html><head><meta charset="utf-8"><title>...</title></head><body>[fragment]</body></html>。またはテンプレート駆動のCSSによる完全にスタンドアロンの出力には--standaloneフラグでPandocを使用してください。

私のMarkdownはどこかに送信されますか?

いいえ。変換はmarked.js経由でブラウザ内で完全に実行されます。貼り付けたMarkdownは決してネットワークを越えません、入力する間にDevToolsのネットワークタブで検証するか、ロード後にページをオフラインに(機内モードに)してコンバーターがまだ機能することを確認してください。機密のドラフト、NDAの下のクライアント納品物、原稿の章または見知らぬ人のハードドライブにコピーされたくないテキストに安全です。

関連ツール