commonmark

リーグ/コモンマーク

League/commonmarkは、Colin O'Dell によって作成された拡張性の高い PHP マークダウン パーサーで、完全な CommonMark 仕様と GitHub 風味のマークダウンをサポートします。 これは、John MacFarlane (@jgm) による CommonMark JS リファレンス実装に基づいています。

インストールと基本的な使い方

このプロジェクトには、 mbstring拡張子を備えた PHP 7.4 以降が必要です。 Composer 経由でインストールするには、次のコマンドを実行するだけです。

 $ 作曲家にはリーグ/コモンマークが必要です

CommonMarkConverterクラスは、CommonMark を HTML に変換するための単純なラッパーを提供します。

 LeagueCommonMarkCommonMarkConverter を使用します;$converter = new CommonMarkConverter(['html_input' => 'strip','allow_unsafe_links' => false,
]);echo $converter->convert('# Hello World!');// <h1>Hello World!</h1>

または、GitHub フレーバーの Markdown が必要な場合は、代わりにGithubFlavoredMarkdownConverterクラスを使用します。

 LeagueCommonMarkGithubFlavoredMarkdownConverter を使用します;$converter = new GithubFlavoredMarkdownConverter(['html_input' => 'strip','allow_unsafe_links' => false,
]);echo $converter->convert('# Hello World!');// <h1>Hello World!</h1>

UTF-8 および ASCII エンコーディングのみがサポートされていることに注意してください。 Markdown で別のエンコーディングが使用されている場合は、このライブラリで実行する前に UTF-8 に変換してください。

注意

ユーザーからの信頼できない入力を解析する場合は、上記の例に従ってhtml_inputとallow_unsafe_linksオプションを設定することを検討してください。詳細については、https://commonmark.thephpleague.com/security/ を参照してください。信頼できないユーザーからの生の HTML 入力も許可することを選択した場合は、追加の HTML フィルタリングを提供するライブラリ (HTML Purifier など) の使用を検討してください。

ドキュメント

高度な使用法、構成、カスタマイズに関する完全なドキュメントは、commonmark.thephpleague.com でご覧いただけます。

⏫ アップグレードする

このライブラリの新しいバージョンにアップグレードする方法については、https://commonmark.thephpleague.com/releases で参照できます。

GitHub 風味のマークダウン

前に示したGithubFlavoredMarkdownConverter 、GFM 仕様にある追加機能を追加するCommonMarkConverterのドロップイン代替品です。

• オートリンク

• 許可されていない生の HTML

• 取り消し線

• テーブル

• タスクリスト

すべてを必要としない場合に特定の GFM 機能のみを含める方法の詳細については、拡張機能のドキュメントを参照してください。

関連パッケージ

統合

• ケーキPHP 3

• ドルパル

• ララベル 4+

• カジカ

• シンフォニー 2 & 3

• シンフォニー 4

• Twig マークダウン拡張機能

• 小枝のフィルターとタグ

• Laravel CommonMark ブログ

付属の拡張機能

このライブラリにバンドルされている拡張機能の完全なリストについては、拡張機能のドキュメントを参照してください。

コミュニティ拡張機能

カスタム パーサー/レンダラーは、CommonMark を拡張する拡張機能にバンドルできます。 以下に興味深いものをいくつか挙げます。

• 絵文字拡張機能 - Github タグを使用した UTF-8 絵文字拡張機能。

• Sup Sub 拡張機能 - 上付き文字と下付き文字 ( <sup>および<sub> HTML タグ) のサポートを追加します。

• YouTube iframe 拡張機能 - YouTube リンクを iframe に置き換えます。

• Lazy Image extension - 画像の遅延読み込みのためのさまざまなオプションを追加します。

• マーカー拡張機能 - 強調表示されたテキスト ( <mark> HTML タグ) のサポートを追加します。

その他のパッケージは、Packagist のcommonmark-extensionパッケージ タイプで見つかります。

独自に構築した場合は、お気軽に PR を送信してこのリストに追加してください。

その他

人々がleague/commonmarkを使って行っているその他の素晴らしいことをチェックしてください: https://packagist.org/packages/league/commonmark/dependents

バージョン管理

SemVer は厳密にフォローされています。マイナー リリースとパッチ リリースでは、コードベースに重大な変更を導入してはなりません。ただし、解析された Markdown の結果の AST または HTML 出力が変更される可能性があります (バグ修正、仕様変更などにより)。その結果、わずかに異なる HTML が得られる可能性がありますが、このライブラリに構築されたカスタム コードは引き続き正しく機能するはずです。

@internalとマークされたクラスやメソッドは、このライブラリの外部で使用することを目的としておらず、いつでも重大な変更が加えられる可能性があるため、使用は避けてください。

メンテナンスとサポート

新しいマイナーバージョン (例: 2.0 -> 2.1 ) がリリースされると、前のバージョン ( 2.0 ) は少なくとも3 か月間はセキュリティと重大なバグの修正を受け続けます。

新しいメジャーバージョンがリリースされると (例: 1.6 -> 2.0 )、以前のバージョン ( 1.6 ) は、新しいリリースのリリース後、少なくとも3 か月間は重大なバグ修正が提供され、セキュリティ アップデートは 6 か月間提供されます。

(このポリシーは将来変更される可能性があり、ケースバイケースで例外が設けられる場合があります。)

新しいリリースやセキュリティ アップデートの通知を含むプロフェッショナル サポートは、Tidelift サブスクリプションを通じて利用できます。

‍ 貢献しています

セキュリティの脆弱性を報告するには、Tidelift のセキュリティ連絡先を使用してください。 Tidelift は修正と開示を当社と調整します。

仕様にバグが見つかった場合は、CommonMark プロジェクトに報告してください。 結果として生じる修正は、最終的にはこのプロジェクトにも実装される予定です。

このライブラリへの貢献、特に次のような貢献は歓迎されます。

• CommonMark 仕様に準拠する能力を損なうことなく、使いやすさや柔軟性を向上させます。

• リファレンス実装に対するミラー修正

• パフォーマンスを最適化する

• CommonMark 仕様への準拠に関する問題を修正

リファレンス実装に加えられた更新を簡単に追跡できるように、コア解析ロジックへの大規模なリファクタリングは可能であれば避けるべきです。そうは言っても、リファレンス仕様から大きく逸脱しない変更や、他の一般的な CommonMark 実装で好まれる変更は絶対に考慮します。

詳細については、「貢献」を参照してください。

テスト

$ コンポーザーテスト

これにより、サポートされている最新の仕様に対してリーグ/コモンマークもテストされます。

パフォーマンスのベンチマーク

付属のベンチマーク ツールを実行すると、 league/commonmarkのパフォーマンスを他の一般的なパーサーと比較できます。

 $ ./tests/benchmark/benchmark.php

クレジットと謝辞

このコードはもともと、John MacFarlane によって作成、保守、および著作権で保護されている CommonMark JS リファレンス実装に基づいていました。 このプロジェクトは彼の仕事なしには存在しなかったでしょう。

そして、素晴らしい貢献者の皆様に多大なる感謝を申し上げます。

スポンサー

また、このプロジェクトの継続的な開発をサポートしてくださっている以下のスポンサーにも心から感謝いたします。

• Tidelift は、プロフェッショナル サポート プログラムを通じてメンテナとエンドユーザーの両方にサポートを提供します

• オープンソース プロファイラー サブスクリプションを提供する Blackfire

• 無料の PhpStorm ライセンスでこのプロジェクトをサポートしてくれた JetBrains

このプロジェクトの開発を後援することに興味がありますか?貢献方法のリストについては、https://www.colinodell.com/sponsor をご覧ください。

ライセンス

League/commonmarkは BSD-3 ライセンスに基づいてライセンスされています。 詳細については、 LICENSEファイルを参照してください。

ガバナンス

このプロジェクトは主に Colin O'Dell によって保守されています。 PHP リーグ リーダーシップ チームのメンバーは、これらの任務の一部を支援する場合があります。

誰が使うの？

このプロジェクトは、Drupal、Laravel Framework、Cachet、Firefly III、Neos、Daux.io などで使用されています。

---

Tidelift サブスクリプションでリーグ/コモンマークのプロフェッショナルなサポートを受けましょう
_{Tidelift は、企業に提供すると同時に、メンテナにとってオープンソースを持続可能なものにするのに役立ちます。
依存関係のセキュリティ、メンテナンス、ライセンスに関する保証。}