Markdown Easy
league/commonmarkライブラリを使用してMarkdown構文をHTMLに変換するシンプルなDrupal用Markdownテキストフィルター。
markdown_easy
インストール
composer require 'drupal/markdown_easy:^2.0'
概要
Markdown Easyは、Markdown構文をHTMLに変換するためのシンプルなDrupalテキストフィルターモジュールです。パース処理には強力なleague/commonmark PHPライブラリを活用し、Drupal管理画面を通じて最小限の設定を提供します。
このモジュールは、異なるニーズに対応する3つのMarkdown「フレーバー」を提供します：標準Markdown（CommonMark仕様）、GitHub-flavored Markdown（テーブル、取り消し線、自動リンク、タスクリスト対応）、Markdown Smörgåsbord（脚注と定義リストを追加）。セキュリティはデフォルトで優先され、HTML入力の除去と安全でないリンクのブロックが有効になっています。
インストール時、Markdown Easyは事前設定済みの「Markdown」テキストフォーマットを自動的に作成します。セキュリティのため、XSS攻撃を防ぐためにDrupal Coreの「許可するHTMLタグを制限し、不正なHTMLを修正する」フィルターがMarkdown Easyフィルターの後に実行されることを強制します。
Features
- 3つのMarkdownフレーバーオプション：標準Markdown（CommonMark）、GitHub-flavored Markdown、拡張機能付きMarkdown Smörgåsbord
- モジュールインストール時に事前設定済みの「Markdown」テキストフォーマットを自動作成
- デフォルトでセキュリティを確保：HTML入力の除去と安全でないリンクのブロックが初期状態で有効
- 「許可するHTMLタグを制限」フィルターがMarkdown Easyの後に実行されることを要求するバリデーションの強制
- 許可タグリストに必要なHTMLタグが不足している場合に管理者に警告するシステム
- 左揃え、中央揃え、右揃えカラムへの自動CSSクラス挿入によるテーブル配置サポート
- 2つのHookによる拡張性：設定用のhook_markdown_easy_config_modify()とMarkdown拡張機能追加用のhook_markdown_easy_environment_modify()
- ステータスレポートページで安全でないテキストフォーマット設定を報告するランタイムステータスチェック
- 非推奨の「改行をHTMLに変換する」フィルターが有効な場合の互換性警告
Use Cases
技術ドキュメントサイト
コンテンツエディターが使い慣れたMarkdown構文で技術ドキュメントを作成できるようにします。GitHub-flavored Markdownを使用すれば、シンタックスハイライト対応のコードブロック、データ表示用のテーブル、チェックリスト用のタスクリストが利用できます。Smörgåsbordフレーバーでは引用や参照用の脚注も追加されます。
開発者向けブログプラットフォーム
開発者がWYSIWYGエディターではなくMarkdownで投稿を書けるブログを作成します。使い慣れた構文により、ワークフローで定期的にMarkdownを使用する技術ライター（READMEファイル、GitHubイシューなど）の抵抗感を軽減します。
静的サイトジェネレーターからの移行
Jekyll、Hugo、その他のMarkdownベースの静的サイトジェネレーターからDrupalに移行する組織は、既存のMarkdownコンテンツを変換せずに保持できます。エディターは使い慣れた同じ構文を使い続けることができます。
Markdown保存型ヘッドレスCMS
フロントエンドが独自にMarkdownレンダリングを処理するヘッドレスDrupal実装向けに、テキストフィールドに生のMarkdownを保存し、Drupal管理画面でのプレビューにMarkdown Easyを使用します。
カスタムMarkdown拡張機能の追加
開発者はhook_markdown_easy_environment_modify()を実装することで、Mentions、Smart Punctuation、カスタム拡張機能など、エコシステムの任意のCommonMark拡張機能を追加して組み込みフレーバーを拡張できます。
Tips
- 最も完全な機能セット（脚注と定義リストを含む）には「Markdown Smörgåsbord」フレーバーを使用してください
- 適切なセキュリティのため、常にMarkdown Easyの後に「許可するHTMLタグを制限」を有効にしてください - これによりXSS攻撃を防ぎます
- ステータスレポートページ（/admin/reports/status）で安全でないテキストフォーマット設定の警告を確認してください
- 新しいHTML要素を追加する際は、テキストフォーマット設定ページに表示されるフィルターのヒントで必要な正確なタグと属性を参照してください
- 脚注のスタイリングやテーブル配置のクラス名をカスタマイズするにはhook_markdown_easy_config_modify()を実装してください
- 高度なカスタマイズには、hook_markdown_easy_environment_modify()を使用してhttps://commonmark.thephpleague.com/2.6/extensions/overview/から任意のCommonMark拡張機能を追加できます
- テーブルの配置（左、中央、右）は自動的にCSSクラスを適用し、テーマでスタイリングできます
Technical Details
Hooks 2
hook_markdown_easy_config_modify
処理前にMarkdownコンバーターの設定をモジュールが変更できるようにします。html_inputやallow_unsafe_linksなどのセキュリティ設定の変更や、脚注やテーブルのレンダリングオプションのカスタマイズに使用できます。
hook_markdown_easy_environment_modify
基本拡張機能がロードされた後にMarkdown環境をモジュールが変更できるようにします。組み込みフレーバーに含まれていない追加のCommonMark拡張機能を追加するために使用できます。
Troubleshooting 8
テキストフォーマット設定ページでフィルターの重みを調整してください。Markdown Easyが「許可するHTMLタグを制限」フィルターより低い重み（先に実行）になるようにしてください。「許可するHTMLタグを制限」フィルターを有効にし、Markdown Easyの後に実行されるよう設定する必要があります。
使用しているテキストフォーマットでMarkdown Easyフィルターが有効になっていることを確認してください。テキストフォーマットがフィールドに割り当てられていること、およびユーザーがそのテキストフォーマットを使用する権限を持っていることを確認してください。
適切なMarkdownフレーバーを選択していることを確認してください（テーブル/取り消し線にはGitHub-flavored、脚注にはSmörgåsbord）。また、対応するHTMLタグが「許可するHTMLタグを制限」フィルターの許可リストに含まれていることを確認してください。
推奨されるHTMLタグと属性を「許可するHTMLタグを制限」フィルターに追加してください。警告には、選択したMarkdownフレーバーとの完全な互換性に必要なタグが正確にリストされています。
デフォルトでは、Markdown Easyはセキュリティのため HTML入力を除去します。HTMLを許可する必要がある場合は、設定でskip_html_input_strippingをtrueに設定するか、hook_markdown_easy_config_modify()を実装してhtml_inputを'allow'に設定してください。
影響を受けるテキストフォーマットで「許可するHTMLタグを制限」フィルターを有効にし、Markdown Easyフィルターの後に実行されるようにしてください。これはXSS攻撃を防ぐためのセキュリティ要件です。
バージョン2.xでは「改行をHTMLに変換する」フィルターは不要になりました。それを無効にし、許可するHTMLタグに<p>と<br>を追加してください。1.xは改行に関してMarkdown仕様に従っていなかったため、既存のコンテンツは異なる表示になる可能性があります。
以前league/commonmarkと共にMarkdownモジュールをインストールしていた場合は、まず古いバージョンを削除してください：composer remove league/commonmark、その後Markdown Easyをインストールします。Markdown Easyはより新しいバージョンのライブラリを必要とします。
Security Notes 6
- デフォルトで、Markdown Easyは最大限のセキュリティのためhtml_input: stripとallow_unsafe_links: falseで実行されます
- モジュールは、変換されたHTML出力をサニタイズするために「許可するHTMLタグを制限」フィルターがMarkdown Easyの後に実行されることを強制します
- フィルター強制の無効化（skip_filter_enforcement）またはHTML除去の無効化（skip_html_input_stripping）は、サイトをXSS脆弱性にさらす可能性があります
- モジュールは安全でない設定のテキストフォーマットについて、ステータスレポートページにランタイム警告を表示します
- Hookを使用してセキュリティ設定を変更する場合は、サイトのセキュリティ体制への影響を理解してください
- drupal.orgのセキュリティカバレッジは「covered」であり、このモジュールはDrupalセキュリティチームによってレビューされています