commonmark

лига/общая марка

League/commonmark — это хорошо расширяемый парсер PHP Markdown, созданный Колином О'Деллом, который поддерживает полную спецификацию CommonMark и Markdown с поддержкой GitHub. Он основан на эталонной реализации CommonMark JS Джона Макфарлейна (@jgm).

Установка и базовое использование

Для этого проекта требуется PHP 7.4 или выше с расширением mbstring . Чтобы установить его через Composer, просто запустите:

 $композитору требуется лига/commonmark

Класс CommonMarkConverter предоставляет простую оболочку для преобразования CommonMark в HTML:

 используйте LeagueCommonMarkCommonMarkConverter;$converter = new CommonMarkConverter(['html_input' => 'strip','allow_unsafe_links' => false,
]);echo $converter->convert('# Привет, мир!');// <h1>Привет, мир!</h1>

Или, если вы хотите использовать Markdown с поддержкой GitHub, используйте вместо этого класс GithubFlavoredMarkdownConverter :

 используйте LeagueCommonMarkGithubFlavoredMarkdownConverter;$converter = new GithubFlavoredMarkdownConverter(['html_input' => 'strip','allow_unsafe_links' => false,
]);echo $converter->convert('# Привет, мир!');// <h1>Привет, мир!</h1>

Обратите внимание, что поддерживаются только кодировки UTF-8 и ASCII. Если ваш Markdown использует другую кодировку, преобразуйте ее в UTF-8, прежде чем запускать ее через эту библиотеку.

Осторожность

Если вы будете анализировать ненадежные данные, поступающие от пользователей, рассмотрите возможность установки параметров html_input allow_unsafe_links в соответствии с приведенным выше примером. Дополнительную информацию см. на https://commonmark.thephpleague.com/security/. Если вы также решили разрешить необработанный ввод HTML от ненадежных пользователей, рассмотрите возможность использования библиотеки (например, HTML Purifier) ​​для обеспечения дополнительной фильтрации HTML.

Документация

Полную документацию по расширенному использованию, настройке и настройке можно найти на commonmark.thephpleague.com.

⏫ Обновление

Информацию о том, как перейти на более новые версии этой библиотеки, можно найти по адресу https://commonmark.thephpleague.com/releases.

Markdown со вкусом GitHub

Показанный ранее GithubFlavoredMarkdownConverter представляет собой замену CommonMarkConverter , которая добавляет дополнительные функции, найденные в спецификации GFM:

• Автоссылки

• Запрещен необработанный HTML-код.

• Зачеркивание

• Таблицы

• Списки задач

Дополнительную информацию о том, как включить только определенные функции GFM, если вы не хотите использовать их все, см. в документации по расширениям.

Сопутствующие пакеты

Интеграции

• ТортPHP 3

• Друпал

• Ларавел 4+

• Бычок

• Симфония 2 и 3

• Симфония 4

• Расширение Twig Markdown

• Фильтр и тег Twig

• Блог Laravel CommonMark

Включенные расширения

Полный список расширений, входящих в состав этой библиотеки, см. в нашей документации по расширениям.

Расширения сообщества

Пользовательские анализаторы/рендереры могут быть объединены в расширения, расширяющие CommonMark. Вот некоторые из них, которые могут показаться вам интересными:

• Расширение Emoji — расширение Emoji UTF-8 с тегом Github.

• Расширения Sup Sub — добавляет поддержку верхнего и нижнего индекса (HTML-теги <sup> и <sub> ).

• Расширение YouTube iframe — заменяет ссылку YouTube на iframe.

• Расширение Lazy Image — добавляет различные варианты отложенной загрузки изображений.

• Расширение маркера — добавляет поддержку выделенного текста (HTML-тег <mark> ).

Другие можно найти на Packagist под типом пакета commonmark-extension .

Если вы создадите свой собственный, не стесняйтесь отправить PR, чтобы добавить его в этот список!

Другие

Узнайте о других интересных вещах, которые люди делают с league/commonmark : https://packagist.org/packages/league/commonmark/dependents

Управление версиями

За SemVer внимательно следят. Второстепенные выпуски и выпуски исправлений не должны вносить критические изменения в кодовую базу; однако они могут изменить результирующий вывод AST или HTML проанализированного Markdown (из-за исправлений ошибок, изменений спецификаций и т. д.). В результате вы можете получить немного другой 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

Благодарности и благодарности

Этот код изначально был основан на эталонной реализации CommonMark JS, которая написана, поддерживается и защищена авторскими правами Джона Макфарлейна. Без его работы этого проекта просто не было бы.

И огромное спасибо всем нашим замечательным участникам:

Спонсоры

Мы также хотели бы выразить нашу искреннюю благодарность следующим спонсорам, которые поддерживают постоянное развитие этого проекта:

• Tidelift за предложение поддержки как сопровождающим, так и конечным пользователям в рамках программы профессиональной поддержки.

• Blackfire за предоставление подписки на Open-Source Profiler

• JetBrains за поддержку этого проекта с помощью бесплатных лицензий PhpStorm.

Вы заинтересованы в спонсировании развития этого проекта? См. https://www.colinodell.com/sponsor, чтобы увидеть список способов внести свой вклад.

Лицензия

лига/общий знак лицензируется по лицензии BSD-3. Более подробную информацию смотрите в файле LICENSE .

Управление

Этот проект в основном поддерживается Колином О'Деллом. Члены руководящей команды PHP League могут время от времени помогать с некоторыми из этих обязанностей.

Кто это использует?

Этот проект используется Drupal, Laravel Framework, Cachet, Firefly III, Neos, Daux.io и другими!

---

Получите профессиональную поддержку для лиги/коммонмарка с подпиской Tidelift
_{Tidelift помогает сделать открытый исходный код устойчивым для специалистов по сопровождению, одновременно предоставляя компаниям
гарантии безопасности, обслуживания и лицензирования их зависимостей.}