Markdown はレンダラーのファミリーです
CommonMark は、段落、見出し、強調、リンク、リスト、ブロック引用符、およびコードの安定したコアを定義します。 GitHub フレーバー付きマークダウンは、テーブル、タスク リスト、取り消し線、自動リンクを追加します。脚注、アラート、絵文字、構文の強調表示、および数式は拡張機能に依存します。
同じソースでも、GitHub、ドキュメント システム、静的ジェネレーター、メモ アプリ、電子メール ツール間で異なるレンダリングが可能です。移植性は、ターゲット レンダラーを特定することから始まります。
耐久性のある構造を構築する
- 1 つの H1 は、宛先がソースでそれを予期している場合にのみ使用します。
- H2 と H3 の順序を論理的に保ちます。
- 不必要な手動改行を行わずに段落を書きます。
- 言語ラベルが付いたフェンスで囲まれたコード ブロックを使用します。
- リンクと画像のパスを安定した状態に保ちます。
- 拡張子が消えてもソースを読めるようにします。
テーブルは便利ですが制限があります
| Need | マークダウンテーブル | Alternative |
|---|---|---|
| コンパクト比較 | Good | None |
| 細胞内の長い散文 | メンテナンスが難しい | 見出しまたは定義リスト |
| 行/列のスパン | ポータブルではない | HTML (許可されている場合) |
| 機械可読データ | Weak | CSV/JSON とレンダリングされたビュー |
タスク リストは表記法であり、プロジェクト データベースではありません
タスク リスト構文は、チェックリスト、リリースの準備、および問題のテンプレートに役立ちます。所有権、期日、依存関係、リマインダー、監査履歴は提供されません。責任が重要な場合は、運用作業をタスク システムに移行します。
脚注とアラートは拡張子に依存します
脚注は補足的な説明を本文から外しますが、CommonMark の核心ではありません。 GitHub アラートは、視覚的なメモ、警告、注意ブロックを追加します。他のレンダラーでは通常の引用符として表示される場合があります。スタイルを付けずに単語が明確に残るように書きます。
強化が消える場合があります。意味は生き残らなければなりません。
コードと数学
言語ヒントを含むフェンスで囲まれたコード ブロックを使用します。ラベルは強調表示を制御します。コードは実行されません。データ パスが承認されていないエディターにシークレットを貼り付けないでください。
数学の構文は KaTeX などのレンダラーに依存します。サポートされていない LaTeX パッケージとコマンドは自動的に動作しません。重要な数式について平易な説明を提供し、最終出力でのアクセシビリティを検証します。
Jivaro のマークダウン エディターを使用する
- Markdown エディターおよびプレビューアー を開きます。
- 空白から始めるか、ファイルをインポートするか、例を使用します。
- 書き込み中にライブ プレビューを確認します。
- 表、タスク、脚注、アラート、コード、絵文字、数学を個別にテストします。
- 自動保存は唯一のバックアップではなく、利便性のために使用してください。
- Markdown を編集可能なマスターとしてエクスポートします。
- レンダリングされた出力が必要な場合は、HTML をエクスポートします。
- エクスポートされた HTML を個別に開き、リンク、見出し、コード、表、および数式を検査します。
HTML エクスポートには信頼境界が必要です
ユーザー制御のマークダウンに生の HTML が含まれる可能性がある場合は、公開する前に出力をサニタイズします。また、エクスポートにスタイルが含まれるか、セマンティック HTML のみが含まれるかを確認してください。貼り付けられた出力は、別のサイトの CSS では異なるように見える場合があります。
移植性チェックリスト
見出し、リンク、リスト、コードは理解可能なままです。
GFM、脚注、アラート、絵文字、または数学が必要かどうかを示します。
リンクされたアセットを予測可能な状態に保ちます。
出力と信頼できない入力を検証します。
レンダリングされた HTML が唯一の編集可能なコピーにはならないようにしてください。
宛先は権威のあるものです。
互換性プロファイルを設計する
繰り返しドキュメントを作成する場合は、サポートするレンダラーと拡張機能を書き留めてください。 GitHub プロファイルでは、GFM テーブルとタスクが許可される場合がありますが、生の HTML は回避されます。技術サイトでは、脚注、構文の強調表示、アラート、KaTeX を追加できます。クロスプラットフォーム プロファイルでは、コンテンツを CommonMark に加えて通常のリンクとフェンスされたコードに制限する場合があります。
アップグレード後に、サポートされている各レンダラを通じて同じフィクスチャ ドキュメントを実行します。フィクスチャには、ネストされたリスト、コード フェンス、テーブル、リンク、画像、Unicode、脚注、アラート、および数学を含める必要があります。相違点は、公開されたドキュメントに影響を与える前に明らかになります。
イメージとソースにリンクされたファイルのバージョンを確認する
壊れた画像やダウンロードは、アセットなしで Markdown を移動することで発生することがよくあります。予測可能な相対パス、説明的なファイル名、生成された HTML の固有のディメンション、およびリンク チェッカーを使用します。ドキュメントが別のプラットフォームにエクスポートまたはコピーされるときは、すべてのローカル アセットが絶対正規 URL に転送または置換されたことを確認してください。
よくある質問
いいえ。これらは通常、GitHub Flavored Markdown などの拡張機能によって提供されます。
いいえ。他のレンダラーでは、通常のブロック引用符またはサポートされていない構文として表示される場合があります。
いいえ。生の HTML と生成された HTML は、宛先の信頼モデルに従ってサニタイズする必要があります。
編集、バージョン管理、別のレンダラーへの移動は依然として簡単です。
関連するJivaroアプリ
CodeMirror、同期スクロール、Mermaid図、フロントマター、表、シンタックスハイライト、数式に対応し、Markdownの作成、検索、プレビュー、読み込み、自動保存、書き出しができます。
アプリを開く出典と参考文献
- CommonMark 仕様XXQPH0002QXZCommonMark · リファレンス
- GitHub フレーバー マークダウン仕様XXQPH0002QXZGitHub · リファレンス
- GitHub の構文の作成と書式設定XXQPH0002QXZGitHub ドキュメント · リファレンス
- KaTeX サポートされている関数KaTeX · リファレンス
- Markdown エディターおよびプレビューアーXXQPH0002QXZJivaro · ファーストパーティ