moxio/commonmark-ext-definition-list

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.

Requirements

This library requires PHP version 7.4 or higher and a 1.x release of
league/commonmark.

Installation

Install as a dependency using composer:

$ composer require --dev moxio/commonmark-ext-definition-list

Usage

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.

Syntax

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 item

Versioning

This project adheres to Semantic Versioning.

Contributing

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.

License

This project is released under the MIT license.

Treeware

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).