私は何年もの間、毎日 Markdown を書いています - プラグイン README、変更ログ、ドキュメント Toolz.dev、WP Adminify のリリース ノート、コミット メッセージの半分。 そしてそのほとんどの時間、私はレンダリング ステップを魔法として扱いました。 アスタリスクを書きますが、GitHub は太字を示します。 いいです。 先に進みます。
次に、Markdown をデータベースから取り出して next.js ページにレンダリングするドキュメント セクションを作成しました。その魔法は、私が下さなければならない非常に具体的な決定のリストに変わりました。 1 つの改行は、 <br>? (GitHub のコメントは、「はい」と答えます。 マークダウン仕様は「いいえ」と言っています。) する <div> ソースで div または文字通りのテキストとしてレンダリングしますか? (誰が質問するか、また作者を信頼するかどうかに依存します。) フェンスで囲まれたコード ブロックに当てはまるクラスはどれですか? なぜパーサーが変わるのですか **bold**text 太字にして、もう 1 つだけは放っておきますか?
どれもエキゾチックではありません。 Markdown は非常に単純に見えるので、人々はその下に何もないと思い込んでいるので、それは誰も教えてくれないことです。 その下にはかなりの数があります。 ザ・ HTML へのマークダウン Toolz.dev のコンバーターは、これらの決定を非表示にするのではなく、スイッチとして公開します。これは、改行が消え続けた理由をデバッグしていたときに必要なこのツールのバージョンです。
tl;dr: Markdown は書き込み形式; HTML は表示形式です. 何かが一方を他方にコンパイルする必要があります. 人々をトリップするルール: 連続する行は 2 つのスペースで行を終了しない限り (または "breaks" オプションをオンにしない限り) 1 つの段落に結合します. raw HTML は parser's の信頼設定に応じて通過またはエスケープされ, GitHub's dialect (GFM) はその上にテーブル, タスクリスト, 取り消し線および bare-URL 自動リンクを追加します 共通マーク ベースライン。フェンスで囲まれたコードがコンパイルされます
<pre><code class="language-js">、これがフック プリズム、Highlight.js 、および Shiki が探しているものです。 ザ・ HTML への Markdown 変換 すべてのスイッチが公開され、これらすべてがブラウザで行われます。
Markdown とは何ですか?なぜ変換が必要なのですか?
Markdown は、John Gruber が 2004 年に公開した平文構文で、設計目標の 1 つを掲げています。Markdown ドキュメントは、タグでマークアップされているように見えずに、そのまま公開でき、平文として読み取れるものでなければなりません。そのため、この構文は、人々がすでに電子メールで使用している慣例から借用しています。強調を表す単語の周りにアスタリスク、見出しの下にダッシュの行、a > 引用のために。
結果として、Markdown はレンダリング形式ではありません。 マークダウンは何も表示されません。 ブラウザーは HTML を表示し、今までにあったすべての場所に みれた レンダリングされた Markdown (GitHub、静的サイト、ドキュメント ポータル、チャット アプリ) は、最初にパーサーを実行し、HTML を画面に表示しました。
ですから、変換はどこかで行わなければなりません。 あなたのオプションは大まかに次のとおりです
- ビルド時に、静的サイト ジェネレーターまたはバンドラーで。 コンテンツがリポジトリに存在する場合は問題ありません。
- リクエストの時間に、サーバー上。 コンテンツがデータベースから取得される場合に必要となります。キャッシュせずにすべてのリクエストでコンテンツを作成すると、コストがかかります。
- ブラウザで、必要な瞬間に必要です。 「この 1 つの目的のためだけに HTML が必要です」に対する答えが、ビルド パイプラインではなく、コピー ペーストである場合に、これはあなたが望むものです。
3 番目のケースは、思ったよりも一般的です。 HTML のみを受け取る CMS フィールドにリリース ノートを貼り付けます。 メール テンプレートに Readme を取得します。 ドキュメントがどのように見えるかを確認する前に、コミットします。 オブシディアンで書かれたドラフトをデザイナーに渡すことができるものに変換します。 パーサーをプロジェクトに配線することを正当化するものはありません。
CommonMark と の 違い は GitHub フレーバーのマークダウン?
Gruber の元の仕様は、散文と Perl スクリプトのページであり、すべての実装が Edge ケースで意見が一致しないほどあいまいなままでした。 共通マーク はそれに対する答えである: 厳密でテスト可能な仕様で、数百の例からなる適合スイートがあるため、2 つの適合するパーサーが同じ入力に対して同一の出力を生成する。 - 見出し、段落、強調、リンク、画像、リスト、ブロッククォート、コード ブロック、テーマ別ブレイク、バックスラッシュ エスケープ、HTML ブロックなどのベースラインを定義します。
GitHub フレーバー マークダウン (GFM) は、GitHub によって指定された正式なスーパーセットであり、人々が求め続けているものを追加します。
| 特集 | 共通マーク | gfm | 構文 |
|---|---|---|---|
| テーブル | いやー | はいって | | a | b | と | --- | --- | 区切り文字列 |
| タスクリスト | いやー | はいって | - [x] done / - [ ] todo |
| 三角 | いやー | はいって | ~~gone~~ |
| 自動リンクされた裸の URL | いやー | はいって | https://toolz.dev ブラケットなし |
| 脚注 | いやー | はい (GitHub 拡張機能) | [^1] |
| 見出し、リスト、コード、強調 | はいって | はいって | 同じ |
マークダウンが GitHub Readme、GitLab Wiki、Notion Export、またはほとんどの最新のエディターから来たものである場合、それは GFM です。 コンバータで GFM をオンにすると、テーブルがリテラル パイプとして表示されます。これは、「コンバーターが壊れています」というサポート 質問です。これらのツールの 1 つを出荷した人なら誰でも受け取れます。
なぜ私の改行が消えたのですか?
マークダウンは、プレーンテキストの電子メールの規則に従って、連続していない行を 1 つの段落として扱います。 これ:
Line one
Line two
プロデュース <p>Line one\nLine two</p>- 1 つの段落、および改行はブラウザがレンダリングするとスペースに折りたたまれます。これはバグではありません。これは仕様であり、テキスト エディターで散文を出力に漏らすことなく 80 列でハードラップできるように存在します。
実際の休憩には 3 つの方法があります。
- 空白行 新しい段落を開始します。 これは、ほとんどの場合、あなたが望むものです。
- 2 つのトレーリング スペース 行の終わりにはハードブレーク - を生成します
<br />。 これは標準的なトリックであり、エディターでは目に見えません。そのため、人々はそれを狂わせます。 - バックスラッシュ 行末は Commonmark で同じようにして、少なくとも目に見える。
そして、混乱の原因となる第 4 の方法があります。 多くのプラットフォームで「ブレーク」モードをオンにします すべての改行がどこになるか <br />。 GitHub のコメントと問題がこれを行います。 ほとんどのチャット アプリはこれを行います。 GitHub Readme ファイル しない。 したがって、同じテキストは、GitHub の問題と同じリポジトリの Readme で異なる方法で表示されます。これは、私たち全員が今に固執している、本当に悪いデザインです。
コンバータはこれをスイッチとして公開します。 ソースがチャット スタイルのレンダラー用に作成された場合は、改行をオンにします。 ドキュメントの場合は、それをオフのままにして、仕様が意図したように空白行を使用してください。
生の HTML はどのように処理されますか?
Markdown はインライン HTML を許可します。元の仕様では、記述した HTML はそのまま通過すると明示的に記載されています。これは、作成者である場合 (作成者が必要な場合) の機能です <details> ブロック、あなたの <img> width 属性を使用すると、アンカーに rel)、そうでない場合は責任です。
HTML パススルーを有効にして信頼できない Markdown をレンダリングすると、XSS の脆弱性が発生します。 <script>alert(document.cookie)</script> 有効なマークダウンです。 もそうです <img src=x onerror="...">。 もそうです <a href="javascript:...">。コメント ボックス、ユーザー プロファイルの略歴、公開 Wiki (見知らぬ人が他の人が読んだ Markdown と書く場所ならどこでも) は、HTML から脱出するか、実際の消毒剤で出力を消毒する必要があります (DOMPurify が通常の答えであり、まさに本物の消毒剤です)。なぜなら、正規表現だけでは敵対的な入力には十分ではないからです。
このコンバーターはデフォルトで 逃げ 生の HTML: <div> ソースに文字通りのテキストとして表示されます <div> 出力では、あなたが書いたかのように <div>。 ソースが自分のものになったときに、パススルーをオンにすることができます。 その設定に関係なく、ライブ プレビューはストリップします。 <script>、 <style>、インライン on* イベント ハンドラと javascript: レンダリング前の URL - 詳細な防御手段であるため、他のユーザーと #39;s README をプレビュー ペインに貼り付けると、コードを実行できません。これはプレビューの安全対策であり、汎用サニタイザーではありません。ユーザーが Markdown をレンダリングする製品を構築している場合は、専用のサニタイザー サーバー サイドを使用し、regex を信頼しないでください。私のものも含まれています。
キャラクターから逃れる必要がある場合 から Markdown だからそれは文字通り - アスタリスクのままであるべきアスタリスク、ファイル名のアンダースコア - バックスラッシュはそれをします: \*not emphasis\*。 そして、あなたが別の方向にエンティティを争っている場合、 HTML エンティティ エンコーダ/デコーダ その仕事のためのツールです。
優れたコンバーターは、実際にどの HTML を発信すべきでしょうか?
セマンティックで退屈なクラスフリー HTML - 1 つの例外があります。
- 見出しになる
<h1>– だよ<h6>。 見出し ID を有効にすると、それぞれがスローグ化されますid、2 つの見出しがタイトルを共有すると重複排除されます (#setup、#setup-1. それが作るもの#anchorディープ リンクは機能し、これはコンテンツ テーブル ジェネレーターがハングアップするものです。 - 情報文字列を持つフェンスで囲まれたブロック -
```jsー なる<pre><code class="language-js">。 *これは例外です。* * 「言語-` クラスは慣習 Prism、Highlight.js と Shiki がすべて探しているので、コンバーターがクラスを発するのはそのためです。 コンバーターはコードに色を付けません。ページのハイライターは、そのフックを必要とします。 - リストは
<ul>/<ol>、そしてここに知っておく価値のある微妙な点があります。 きつい リスト (アイテム間に空白の行はありません) テキストを直接中に入れます<li>、 ゆるい リスト (アイテム間の空欄) 各アイテムのコンテンツをラップします。<p>。 これは、癖ではなく、一般的な行動であり、2 つの箇条の間に空白の行を追加すると、リストが突然垂直方向に伸びるのはそのためです。 CSS は壊れていません。HTML は本当に変更されています。 - テーブルが本物になる
<table>/<thead>/<tbody>マークアップ、style="text-align:center"区切り文字列が使用する場合のセル:---:。 - タスクリストは
<input type="checkbox" disabled>中の<li>、これはまさに GitHub が発するものです。
コンテンツ優先、ラッパー div も、ユーティリティ クラスもありません。 外側からスタイリングします。 .prose クラスまたは独自のルールで、マークアップは移植性のあるままです。
コンバーターの使い方は？
ステップ 1: マークダウンを貼り付けます
README、変更履歴、リリースノート、下書きをドロップインします。入力すると出力は更新されます。変換ボタンがなく、何もアップロードされません。
ステップ 2: スイッチを設定する
ギザブ味 ソースにテーブル、タスク リスト、または取り消し線があるかどうか (おそらくそうです)。 見出し ID アンカーが必要な場合はオン。 改行 ソースがチャット スタイルのレンダラー用に作成された場合にのみオンになります。 生の HTML を許可 ソースがあなたのものである場合にのみオンにします。 完全なドキュメント doctype、charset、viewport、および <title> 最初から撮った <h1>- 結果をブラウザで直接開きたい場合、または静的ホストにドロップしたい場合に便利です。
ステップ 3: プレビューを確認する
プレビュータブに切り替えて構造を確認します。 stats 行は単語、見出し、リンク、画像、コードブロック、読み取り時間を教えてくれます - 投稿をチェックするのに便利なのは、投稿を公開する前だと思っていた長さです。 より徹底的にカウントするには、 ワードカウンター 同じテキストで読みやすさとキーワードの密度を示します。
ステップ 4: 出力を取る
HTML をコピーして、ダウンロードして .html 生成された目次 (各見出しアンカーにリンクする Markdown ネスト リスト) をファイルまたはコピーして、ドキュメントの上部に貼り付ける準備ができています。
バイトが重要なページに結果を貼り付けている場合は、 HTML ミニファイア その後。 コンバータの出力は、ワイヤーのためではなく、読みやすさのためにインデントされています。
よくある使用例
Web サイトに読み込みをする
プラグインとパッケージの作成者は、適切な Readme を作成し、ランディング ページに同じコンテンツを必要とします。 Readme は、テーブルとバッジを備えた GFM であり、ランディング ページには HTML が必要です。 既存の CSS で変換、貼り付け、スタイルを設定します。 見出し ID には、無料でサイドバー TOC が提供されます。
HTML のみを受け入れる CMS への公開
たっぷりのCMSフィールド、電子メールプラットフォーム、レガシー管理パネルはHTMLを取るだけで、他の何も取らない あなたがMarkdownでドラフトする - そして定期的に書くほとんどの人がする - これは橋で変換します 完全なドキュメント オフにして、ページ全体ではなくフラグメントを取得し、フィールドに貼り付けます。
ドキュメント ページのプロトタイプ作成
コンテンツをドキュメント サイトにコミットする前に、ローカルに変換すると、実際の見出し階層と、コード フェンスが適切な言語を持っているかどうかが表示されます。 あい h3 だったはず h2 目次では明らかで、ソースでは見えません。
他の人が書いたコンテンツの監査
投稿者& #39; s Markdownを貼り付け、放出されたHTMLを見て、あなたはすぐに彼らが本物の見出しを使用するか、または行を太字にして偽物 - 文書の構造とアクセシビリティを破壊する習慣 - スクリーンリーダーは見出し; によってナビゲートします **Big Text** は見出しではありません。太字の段落で、コンバーターは 1 行の出力を示しています。
目次を抽出する
長いドキュメントには 1 つが必要であり、手作業で維持すると、古いドキュメントが古くなることが保証されます。 見出しから生成し、貼り付けて、見出しが変更されるたびに再生成します。
詳細: このパーサーが行うことと実行しないこと
これは依存関係のない約 400 行の手書きのパーサーです。これは意図的なものです。なぜなら、全体のポイントが速いページに 200 KB の依存関係を引き込む Markdown パーサーは悪い取引だからです。
カバー: ATX 見出し (# x) と SetExt の見出し (下線付き) === / ---)、段落、強調と強力な (*、 _、 **、 __)、バックティック ラン マッチングを含むインライン コード、情報文字列を含むフェンスで囲まれたコード、インデントされたコード ブロック、遅延継続を伴うブロック引用符、ネストされたリスト (順序付けされたものと順序付けられていない、タイトなリンク)、タイトル付きのテーマ別ブレーク、リンクと画像、アングル ブラケット オートリンク、メール オートリンク、バックスラッシュ エスケープ、GFM セット: 整列、タスク リスト、ベア URL 自動リンク。
カバーされていません: 参照スタイルのリンク ([text][ref] と [ref]: url 他の場所で定義)、脚注、定義リスト、および段落を中断する HTML ブロックの周りにあるいくつかの真にあいまいな共通マークのコーナー ケース。 Commonmark Conformance Suite に対して実行している場合、100% のスコアはありません。 Readme、ChangeLog、またはブログ投稿を変換している場合、気付かないでしょう。
これは正直な取引であり、コンバーターが即座にロードされ、ネットワークがオフになっているのにその理由です。 ビットの正確な共通マークの適合性が必要なコンテンツ パイプラインの場合は、次のようにします。 markdown-it、 remark や cmark あなたのビルドで、それが彼らの目的です。
フェイク
マークダウンを HTML に変換するにはどうすればよいですか?
Markdownをエディタに貼り付けると、HTMLがすぐに表示されます - 変換ボタンもアップロードするファイルもありません ソースがテーブルまたはタスクリストを使用している場合はGitHub Flavored Markdownをオンにしてから、HTMLをコピーするか、.htmlファイルとしてダウンロードします すべてブラウザで実行されるため、未公開の下書きや内部ドキュメントはデバイスから離れることはありません。
GitHub フレーバー マークダウンとは何ですか?
GitHub フレーバー マークダウン (GFM) は、表、タスク リスト チェックボックス、ダブル チルドを使用した取り消し線、および裸の URL の自動リンクを追加する、正式に指定された Commonmark のスーパーセットです。 これは、GitHub が Readme ファイルと問題をレンダリングするために使用する方言であり、今日のほとんどの Markdown エディターが発信するものです。 このコンバーターではデフォルトで有効になっています。
なぜ私のシングルラインが壊れたの?
標準のマークダウンは、連続する行を 1 つの段落に結合します。行を 2 つ空けて終了する場合、または、後続のバックスラッシュを使用する場合、または空白のままにした場合にのみ行区切りが生き残ります。 すべての改行を <br />、改行オプションを有効にします - それはGitHubのコメントとほとんどのチャットアプリが使用する動作ですが、READMEファイルが行うものではありません。
コンバータは私のコードを強調表示しますか?
ハイライターが必要とするマークアップを発行しますが、コード自体は色を付けません。 言語でタグ付けされたフェンスで囲まれたコード ブロック js なる <pre><code class="language-js">、これは、クラス コンベンション プリズム、Highlight.js と Shiki が探しているものです。 出力を貼り付けるページに、これらのライブラリの 1 つを追加すると、ハイライトが自動的に表示されます。
マークダウン内の生の HTML は保持されますか?
デフォルトではエスケープされます。 <div> タグではなくリテラルテキストとして表示されます。 allow-raw-HTML オプションをオンにして、タグをまっすぐに渡します。 markdown が意図的に HTML で混在するときに必要なものです - a <details> ブロック、または属性のある画像。 信頼できない作成者からの生の HTML は XSS ベクトルであるため、信頼できるソースに対してのみ有効にしてください。
書いていないマークダウンを貼り付けても安全ですか?
はい。 HTML はデフォルトでエスケープされ、ライブ プレビューではスクリプト タグとスタイル タグ、インライン イベント ハンドラー、および javascript: レンダリング前の URL がさらに削除されます。どこにでも貼り付けるものは何もありません。見知らぬ人から Markdown をレンダリングする製品を構築している場合は、DOMPurify サーバー側などの専用のサニタイザーを使用してください。プレビュー フィルターは、その代替ではありません。
見出しから目次を生成できますか?
はい。 ヘッディング ID を有効にすると、すべての見出しがスローグされて重複排除されたアンカーを取得し、ツールは各アンカーにリンクする Markdown 目次を作成します。 それをドキュメントの先頭にコピーして、リンクは生成された ID に対して解決します。 見出しが変更されたときに、手で維持するのではなく、再生成してください。
このコンバーターは Commonmark を完全に実装していますか?
これは、人々が実際に書く構成要素 - ATX および setext の見出し、段落、強調、リンク、画像、オートリンク、ブロッククオート、ネストおよびルーズリスト、フェンスで囲まれたインデントされたコード、テーマ別ブレイク、バックスラッシュエスケープ - に加えて、GFM 拡張機能リファレンススタイルのリンク、脚注、およびいくつかのまれな CommonMark HTML ブロックエッジケースはカバーされていません。 build パイプラインでのビット正確な適合には、markdown-it、remark、または cmark を使用します。
関連ツール: HTML へのマークダウン ・ HTML エンティティ ・ HTML ミニファイア ・ ワードカウンター ・ スラッグジェネレーター
関連する読み物: Web 開発者のツールキット ・ テキスト ツール ガイド
