PHP Markdown

by Michel Fortin
https://michelf.ca/

based on Markdown by John Gruber
https://daringfireball.net/

Введение

Это библиотечный пакет, который включает в себя PHP Markdown парсер и его родственный пакет PHP Markdown Extra с дополнительными функциями.

Markdown — это инструмент для конвертации текста в HTML для веб-писателей. Markdown позволяет писать с использованием простого и легко читаемого формата текста, а затем конвертировать его в структурно правильный XHTML (или HTML).

"Markdown" на самом деле представляет собой две вещи: синтаксис разметки простым текстом и программное обеспечение, первоначально написанное на Perl, которое конвертирует простой текст в HTML. PHP Markdown — это порт оригинальной программы Markdown Джона Грубера на PHP.

• Полная документация синтаксиса Markdown
  — Daring Fireball (John Gruber)
• Дополнительные синтаксисы Markdown Extra
  — Michel Fortin

Требования

Этот библиотечный пакет требует PHP 7.4 или более поздней версии.

Примечание: более старый пакет-плагин/библиотека для PHP Markdown и PHP Markdown Extra больше не поддерживается, но будет работать с PHP 4.0.5 и более поздней версией.

Возможно, вам потребуется установить pcre.backtrack_limit выше 1 000 000 (по умолчанию), хотя значение по умолчанию обычно подходит.Использование

Чтобы использовать этот библиотечный пакет с Composer, сначала установите его с помощью:

$ composer require michelf/php-markdown

Затем включите сгенерированный файл autoload.php Composer для [включения автозагрузки]:

require 'vendor/autoload.php';

Без Composer, для работы автозагрузки, вашему проекту требуется автозагрузчик совместимый с PSR-4 или PSR-0. См. включенный файл Readme.php для минимальной установки автозагрузки. (Если вы не можете использовать автозагрузку, см. ниже.)

С автозагрузкой классов:

use Michelf\Markdown;
$my_html = Markdown::defaultTransform($my_text);

Синтаксис Markdown Extra также доступен таким же образом:

use Michelf\MarkdownExtra;
$my_html = MarkdownExtra::defaultTransform($my_text);

Если вы хотите использовать PHP Markdown с другим фильтром текста, построенным для парсинга HTML, вы должны фильтровать текст после вызова функции transform. Это пример с [PHP SmartyPants]: Используйте Michelf\Markdown, Michelf\SmartyPants; $my_html = Markdown::defaultTransform($my_text); $my_html = SmartyPants::defaultTransform($my_html);

Все эти примеры используют статическую функцию defaultTransform, расположенную внутри класса парсера. Если вы хотите настроить конфигурацию парсера, вы также можете создать экземпляр напрямую и изменить некоторые переменные конфигурации:

Используйте Michelf\MarkdownExtra;
$parser = new MarkdownExtra;
$parser->fn_id_prefix = "post22-";
$my_html = $parser->transform($my_text);

Для получения дополнительной информации см. полный список [переменных конфигурации]. [включить автозагрузку]: https://getcomposer.org/doc/01-basic-usage.md#autoloading [PHP SmartyPants]: https://michelf.ca/projects/php-smartypants/ [переменные конфигурации]: https://michelf.ca/projects/php-markdown/configuration/

Использование без автозагрузки

Если вы не можете использовать автозагрузку классов, вы все равно можете использовать include или require для доступа к парсеру. Чтобы загрузить парсер Michelf\Markdown, сделайте это следующим образом:

require_once 'Michelf/Markdown.inc.php';

Или, если вам нужен парсер Michelf\MarkdownExtra:

require_once 'Michelf/MarkdownExtra.inc.php';

При использовании простых файлов .php автозагрузка требуется для корректной работы, в то время как использование файлов .inc.php позволяет загружать зависимости сразу, а не по требованию, как при использовании автозагрузки.

Публичный API и политика версионирования

Номера версий имеют формат major.minor.patch.

Публичный API PHP Markdown состоит из двух классов парсера Markdown и MarkdownExtra, их конструкторов, функций transform и defaultTransform и их переменных конфигурации. Публичный API стабилен для заданного номера основной версии. Он может получать дополнения при увеличении номера минорной версии.Защищённые члены не считаются публичным API. Это нестандартно и требует объяснения. Увеличение номера основной версии каждый раз, когда меняется подходящая реализация, приведёт к ненужным номерам версий для большинства людей, которые просто используют парсер. Защищённые члены предназначены для создания подклассов парсера, которые ведут себя по-разному. Очень мало людей создают подклассы парсера. Я не хочу отбивать желание делать это, делая всё приватным, но в то же время я не могу гарантировать стабильные подключения между версиями, если вы используете защищённые члены.Изменения синтаксиса увеличивают мажорную версию для новых функций и младшую версию для небольших исправлений. Новая функция — это то, что требует изменения в документации по синтаксису. Обратите внимание, что, так как библиотека PHP Markdown включает два парсера, изменение синтаксиса для любого из них увеличивает мажорную версию. Также обратите внимание, что нет ничего, которое было бы идеально совместимо в обратном направлении с синтаксисом Markdown: все входные данные всегда являются валидными, поэтому новые функции всегда заменяют что-то, что было ранее легальным, хотя обычно это бессмысленно.Проблемы

Чтобы отправить отчет о баге, пожалуйста, отправьте электронное письмо на: michel.fortin@michelf.ca

Пожалуйста, включите в ваш отчет: (1) пример входных данных; (2) ожидаемый выход; (3) фактический выход, сгенерированный PHP Markdown.

Если у вас есть проблема, при которой Markdown возвращает пустой результат, сначала проверьте, что предел обратного отслеживания не слишком низкий, запустив php --info | grep pcre. Подробности см. в разделе "Установка и требования" выше.

Разработка и тестирование

Приглашаются pull requests для устранения багов. Предложенные новые функции будут тщательно проверены — учитывая совместимость в обратном направлении, потенциальные побочные эффекты и возможности будущего расширения — перед принятием или отклонением.

Если вы отправляете pull request, который включает изменения в парсер, пожалуйста, добавьте тесты для изменений в директорию test/. Это может быть просто добавлением файла .text (входные данные) с соответствующим файлом .xhtml (выходные данные) в соответствующую категорию под ./test/resources/.

Традиционно тесты находились в отдельном репозитории, MDTest, но теперь они расположены здесь, рядом с исходным кодом.

Донаты

Если вы хотите сделать донат, который поможет мне уделять больше времени PHP Markdown, пожалуйста, посетите [michelf.ca/donate].[michelf.ca/donate]: https://michelf.ca/donate/#!Спасибо%20за%20PHP%20Markdown

История версий

PHP Markdown Lib 2.0.0 (26 Сентября 2022)

• Теперь требуется версия PHP 7.4 или выше.

• Добавлены аннотации типов для свойств конфигурации парсера. (Спасибо Тач Тачелоски.)

• Исправлено исключение TypeError в PHP 8, вызванное недействительной переменной-счетчиком. (Спасибо Алексею Копытко.)

• Пакет Composer теперь исключает файлы разработки. (Спасибо Седрику Анне.)

PHP Markdown Lib 1.9.1 (23 Ноября 2021)

• Теперь элементы <details> и <summary> обрабатываются как блочные, поэтому они не обрамляются в <p>. (Спасибо Томасу Хокштейну за исправление.)

• Исправлено непреднамеренное создание пустого атрибута заголовка при добавлении дополнительных атрибутов к ссылке в Markdown Extra. (Спасибо Ричи Блэку за исправление.)

PHP Markdown Lib 1.9.0 (1 Декабря 2019)

• Добавлен конфигурационный параметр fn_backlink_label для вставки текста в атрибут aria-label. (Спасибо Сонни Уокеру за реализацию.)

• Встречаемые в fn_backlink_html, fn_backlink_class, fn_backlink_title и fn_backlink_label символы "^^" будут заменены соответствующим номером примечания в HTML-выводе. Встречаемые символы "%%" будут заменены номером ссылки (примечания могут иметь несколько ссылок). (Спасибо Сонни Уокеру за реализацию.)* Добавлен конфигурационный параметр omit_footnotes. Когда установлено значение true, примечания не добавляются в конец сгенерированного HTML, а переменная footnotes_assembled будет содержать HTML для списка примечаний, что позволяет переместить примечания в другое место на странице. (Спасибо Джеймсу К. за реализацию.) Примечание: при размещении содержимого footnotes_assembled на странице, рассмотрите возможность добавления атрибута role="doc-endnotes" к <div> или <section>, которые будут окружать список примечаний, чтобы они были доступны для средств доступности так же, как это было бы с использованием стандартного HTML-вывода.

• Исправлены предупреждения о устаревании от PHP о использовании фигурных скобок для доступа к символам в строках текста. (Спасибо Реми Коллету и Франсу-Виллему Посту.)

PHP Markdown Lib 1.8.0 (14 января 2018)

• Автоматическая загрузка с помощью Composer теперь использует PSR-4.

• HTML-вывод для примечаний в Markdown Extra теперь включает атрибуты role с значениями из WAI-ARIA для улучшения доступности. (Спасибо Тобиасу Бенгфарту)

• В Markdown Extra добавлен конфигурационный параметр hashtag_protection. Когда установлено значение true, это предотвращает интерпретацию ATX-стилевых заголовков без пробела после начального символа # как заголовков. Таким образом, ваши ценные хэш-теги сохраняются. (Спасибо Жюссону Тимотею за реализацию.)

PHP Markdown Lib 1.7.0 (29 октября 2016)

• Добавлен конфигурационный параметр hard_wrap, который преобразует все символы новой строки в тексте в теги <br> в HTML-выводе. По умолчанию, согласно стандартной синтаксису Markdown, эти символы новой строки игнорируются, если они не предшествуют двум пробелам. Спасибо Джонатану Кохлмайеру за реализацию.* Улучшена обработка элементов списка для устранения проблемных случаев, выявленных с добавлением hard_wrap. Это должно не повлиять на вывод, за исключением элементов списка, которые заканчиваются двумя пробелами (и, следовательно, заканчиваются переносом строки).

• Добавлен конфигурационный параметр code_span_content_func, который принимает функцию, преобразующую содержимое тега кода в HTML. Это может быть полезно для реализации подсветки синтаксиса. В отличие от эквивалента для блока кода, в этом случае нет синтаксиса для указания языка. Спасибо стиикситу за реализацию.

• Устранена проблема Markdown Extra, связанная с тем, что двойные пробелы в конце строки не приводили к переносу строки внутри HTML-блоковых элементов, таких как <p markdown="1">, где элемент ожидает только элементов уровня span.

• В коде парсера перешли на формат комментариев PHPDoc. Спасибо Робби Авериллу за помощь.

PHP Markdown Lib 1.6.0 (23 декабря 2015)

Примечание: эта версия была неправильно выпущена как 1.5.1 22 декабря, номер, который противоречит политике версионирования.

• Для блоков кода с ограждением в Markdown Extra теперь можно задать имя класса для языка блока кода перед специальным атрибутным блоком. Ранее, это имя класса было разрешено только в отсутствие специального атрибутного блока.* Добавлен конфигурационный параметр code_block_content_func, который принимает функцию, преобразующую содержимое блока кода в HTML. Это особенно полезно для подсветки синтаксиса. Для блоков кода с ограждением в Markdown Extra функция имеет доступ к имени класса языка (тому, что находится вне специального атрибутного блока). Спасибо Марии Конрад за предоставление реализации.

• Символ кривой стрелки для обратной ссылки в примечаниях теперь сопровождается селектором варианта Unicode для предотвращения его отображения в виде эмодзи на iOS.

Примечание: в более старых браузерах селектор варианта часто интерпретируется как отдельный символ, делая его видимым после стрелки. Поэтому теперь есть также конфигурационный параметр fn_backlink_html, который можно использовать для установки текста ссылки на что-то другое. Спасибо Дане за предоставление реализации.

• Исправлена проблема в MarkdownExtra, где длинные заголовки, за которыми следовал блок с особым атрибутом, приводили к превышению лимита откатывания и возвращали пустую строку.

PHP Markdown Lib 1.5.0 (1 марта 2015)

• Добавлена возможность начинать нумерованные списки с номера, отличного от 1, и отражать это в HTML-выводе. Это можно включить с помощью конфигурационной переменной enhanced_ordered_lists для парсера Markdown; по умолчанию она включена для Markdown Extra. Автор реализации: Matt Gorle.* Добавлена возможность вставлять пользовательские HTML-атрибуты с простыми значениями везде, где разрешены дополнительные атрибутные блоки (ссылки, изображения, заголовки). Значение должно быть не заключено в кавычки, не содержать пробелов и быть ограничено алфавитно-цифровыми ASCII-символами. Автор реализации: Peter Droogmans.

• Добавлена конфигурационная переменная header_id_func, которая принимает функцию, способную сгенерировать значение атрибута id из текста заголовка. Автор реализации: Evert Pot.

• Добавлена конфигурационная переменная url_filter_func, которая принимает функцию, способную переписать любую ссылку или URL изображения на что-то другое.

PHP Markdown Lib 1.4.1 (4 мая 2014)

• Парсер HTML-блоков теперь будет рассматривать <figure> как блочный элемент (как и следует) и больше не будет обрамлять его в <p> или интерпретировать его содержимое как синтаксис Markdown (хотя с Extra вы можете использовать markdown="1", если хотите использовать синтаксис Markdown внутри него).

• Содержимое элементов <style> теперь оставляется без изменений, его содержимое не будет интерпретироваться как Markdown.

• Исправлена ошибка, при которой некоторые встроенные ссылки с пробелами не работали даже при обрамлении их угловыми скобками:

    [link](<s p a c e s>)* Исправлена проблема, при которой адреса электронной почты с кавычками не всегда имели кавычки экранированными в атрибуте ссылки, что приводило к повреждённым ссылкам (и недействительным HTML).* Исправлен случай, когда определение ссылки, следующее за определением примечания, усваивалось примечанием, если между ними не было пустой строки.

PHP Markdown Lib 1.4.0 (29 ноября 2013)

• Добавлена поддержка URL-схемы tel: в автоматических ссылках.

    <tel:+1-111-111-1111>

  Это преобразуется в следующее (обратите внимание, что префикс tel: становится невидимым): +1-111-111-1111

• Добавлены заключенные в обратные апострофы блоки кода в MarkdownExtra, оригинально из Github-Flavored Markdown.

• Добавлен интерфейс, называемый MarkdownInterface, реализуемый как Markdown, так и MarkdownExtra парсерами. Вы можете использовать этот интерфейс, если хотите создать объект-макет парсера для юнит-тестирования.

• Для тех, кто не может использовать автозагрузку классов, теперь вы можете включить Michelf/Markdown.inc.php или Michelf/MarkdownExtra.inc.php (учтите расширение .inc.php), чтобы автоматически включить другие необходимые файлы парсера.

PHP Markdown Lib 1.3 (11 апреля 2013)

Это первая версия PHP Markdown Lib. Этот пакет требует PHP версии Yöntem 5.3 или новее и предназначен для работы с автозагрузкой PSR-0 и, опционально, с Composer. Вот список изменений с момента PHP Markdown Extra 1.2.6:

• Интерфейс плагина для WordPress и других систем больше не присутствует в пакете Lib. Классический пакет все еще доступен, если вам это нужно: https://michelf.ca/projects/php-markdown/classic/* Добавлены публичные и защищённые атрибуты защиты, а также раздел о том, что является "публичным API" и что нет, в файле Readme.

• Изменено HTML-вывод для примечаний: теперь вместо добавления атрибутов rel и rev ссылки на примечания имеют класс footnote-ref, а обратные ссылки имеют класс footnote-backref.

• Исправлены некоторые регулярные выражения, чтобы сделать PCRE не выдавал предупреждения о POSIX классах сопоставления (в зависимости от вашей версии PCRE).

• Добавлены опциональные класс и id атрибуты для изображений и ссылок с тем же синтаксисом, что и для заголовков:

    [link](url){#id .class}
    ![img](url){#id .class}

  Это работает и для ссылок и изображений в стиле ссылок на ссылки. В этом случае вам нужно добавить эти атрибуты к определению ссылки:

    [link][linkref] или [linkref]
    ![img][linkref]
  
    [linkref]: url "необязательное заголовок" {#id .class}

• Исправлено сообщение PHP-предупреждения, которое срабатывает, когда отсутствуют разделители столбцов таблицы на строке-разделителе под заголовками столбцов.

• Исправлен небольшой недочёт, который мог бы привести к тому, что парсер сохраняет недопустимое состояние, связанное с парсингом ссылок через несколько запусков. Это никогда не наблюдалось (по крайней мере, по моему мнению), но всё равно стоит исправить.

Copyright и Лицензия

PHP Markdown Lib Copyright (c) 2004-2022 Michel Fortin https://michelf.ca/
Все права защищены.Основано на Markdown
Copyright (c) 2003-2005 John Gruber
https://daringfireball.net/
Все права защищены.

Редистрибуция и использование в форме исходного кода и двоичной формы, с изменениями или без, разрешены при условии соблюдения следующих условий:

• Редистрибуция исходного кода должна сохранять вышеуказанное уведомление об авторском праве, этот список условий и нижеуказанное освобождение от ответственности.

• Редистрибуция в двоичной форме должна воспроизводить вышеуказанное уведомление об авторском праве, этот список условий и нижеуказанное освобождение от ответственности в документации и/или других материалах, предоставляемых вместе с редистрибуцией.

• Названия "Markdown" и имена его участников не могут использоваться для одобрения или продвижения продуктов, созданных на основе этого программного обеспечения, без предварительного письменного разрешения.Это программное обеспечение предоставляется авторами и участниками "как есть", и любые явные или неявные гарантии, включая, но не ограничиваясь, неявные гарантии пригодности для продажи и пригодности для определенного назначения, отвергаются. Ни при каких обстоятельствах авторы авторского права или участники не будут нести ответственности за любые прямые, косвенные, случайные, специальные, образцовые или последственное ущербы (включая, но не ограничиваясь, закупку заменяющих товаров или услуг; потерю использования, данных или прибыли; или прерывание бизнеса), независимо от причины, на любом основании ответственности, будь то в контракте, строгой ответственности или деликте (включая неосторожность или иное), возникшее каким-либо образом из-за использования этого программного обеспечения, даже если они были уведомлены о возможности такого ущерба.