Extension for the league/commonmark Markdown parser to support definition lists.
Uses unofficial markdown syntax based on the syntax supported by PHP Markdown Extra, Pandoc and markdown-it. See the section Syntax below for details.
This library requires PHP version 7.4 or higher and a 1.x release of
league/commonmark.
Install as a dependency using composer:
$ composer require --dev moxio/commonmark-ext-definition-list
Add DefinitionListExtension as an extension to your CommonMark environment
instance and you're good to go:
use League\CommonMark\CommonMarkConverter;
use League\CommonMark\Environment;
use Moxio\CommonMark\Extension\DefinitionList\DefinitionListExtension;
$environment = Environment::createCommonMarkEnvironment();
$environment->addExtension(new DefinitionListExtension());
// Use $environment when building your CommonMarkConverter
$converter = new CommonMarkConverter([], $environment);
echo $converter->convertToHtml('
Term 1
: Definition of term 1.
Term 2
: Definition of term 2.
');See the CommonMark documentation for more information about using extensions.
The supported markdown syntax is based on the one used by
PHP Markdown Extra,
Pandoc and
markdown-it.
Since there are subtle differences between the syntaxes understood by these
libraries and there is no formally defined standard, 100% compatibility
with any of the aforementioned libraries cannot be guaranteed. The use
of the tilde (~) as a definition list marker (as understood by Pandoc)
is also supported.
A simple example:
Apple
: Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.
Orange
: The fruit of an evergreen tree of the genus Citrus.The will yield HTML output like:
<dl>
<dt>Apple</dt>
<dd>Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.</dd>
<dt>Orange</dt>
<dd>The fruit of an evergreen tree of the genus Citrus.</dd>
</dl>A more complex example:
Term 1
: This is a definition with two paragraphs. Lorem ipsum
dolor sit amet, consectetuer adipiscing elit. Aliquam
hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet
vitae, risus.
: Second definition for term 1, also wrapped in a paragraph
because of the blank line preceding it.
Term 2
: This definition has a code block, a blockquote and a list.
code block.
> block quote
> on two lines.
1. first list item
2. second list itemThis project adheres to Semantic Versioning.
Contributions to this project are more than welcome. When reporting an issue, please include the input to reproduce the issue, along with the expected output. When submitting a PR, please include tests with your changes.
This project is released under the MIT license.
This package is Treeware. If you use it in production, then we'd appreciate it if you buy the world a tree to thank us for our work. By contributing to the Treeware forest you'll be creating employment for local families and restoring wildlife habitats.
Made with love, coffee and fun by the Moxio team from Delft, The Netherlands. Interested in joining our awesome team? Check out our vacancies (in Dutch).