moxio / commonmark-ext-fancy-lists
Extension for league/commonmark to support additional numbering types for ordered lists
Installs: 61 640
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 11
Forks: 0
Open Issues: 0
Type:commonmark-extension
Requires
- php: ^7.4 || ^8.0
- ext-ctype: *
- ext-mbstring: *
- league/commonmark: ^2.0
- league/config: ^1.1.1
- nette/schema: ^1.2
- wandersonwhcr/romans: ^1.2
Requires (Dev)
- phpunit/phpunit: ^9.3
README
moxio/commonmark-ext-fancy-lists
Extension for the league/commonmark
Markdown parser to support additional numbering types for ordered lists.
Uses unofficial markdown syntax based on the syntax supported by Pandoc. See the section Syntax below for details.
The parser is a modified version of the original ListBlockStartParser
and related classes from league/commonmark
by Colin O'Dell, which is licensed
under the BSD-3-Clause License. It is in turn based on the
CommonMark JS reference implementation
by John MacFarlane.
Requirements
This library requires PHP version 7.4 or higher and a 2.x
release of
league/commonmark
.
Installation
Install as a dependency using composer:
$ composer require --dev moxio/commonmark-ext-fancy-lists
Usage
Add FancyListsExtension
as an extension to your CommonMark environment
instance and you're good to go:
use League\CommonMark\Environment\Environment; use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension; use League\CommonMark\MarkdownConverter; use Moxio\CommonMark\Extension\FancyLists\FancyListsExtension; $environment = new Environment(); $environment->addExtension(new CommonMarkCoreExtension()); $environment->addExtension(new FancyListsExtension()); // Use $environment when building your MarkdownConverter $converter = new MarkdownConverter($environment); echo $converter->convertToHtml(' a) foo b) bar c) baz ');
See the CommonMark documentation for more information about using extensions.
Syntax
The supported markdown syntax is based on the one used by Pandoc.
A simple example:
i. foo ii. bar iii. baz
The will yield HTML output like:
<ol type="i"> <li>foo</li> <li>bar</li> <li>baz</li> </ol>
A more complex example:
c. charlie #. delta iv) subfour #) subfive #) subsix #. echo
A short description of the syntactical rules:
- Apart from numbers, also letters (uppercase or lowercase) and Roman numerals (uppercase or lowercase) can be used to number ordered list items. Like lists marked with numbers, they need to be followed by a single right-parenthesis or period.
- Changing list marker types (also between uppercase and lowercase, or the symbol after the 'number') starts a new list.
- The numeral of the first item determines the numbering of the list.
If the first item is numbered "b", the next item will be numbered
"c", even if it is marked "z" in the source. This corresponds to
the normal
league/commonmark
behavior for numeric lists, and essentially also implements Pandoc'sstartnum
extension. - If the first list item is numbered "I" or "i", the list is considered to be numbered using Roman numerals, starting at 1. If the list starts with another single letter that could be interpreted as a Roman numeral, the list is numbered using letters: a first item marked with "C." uses uppercase letters starting at 3, not Roman numerals starting a 100.
- In subsequent list items, such symbols can be used without any ambiguity: in "B.", "C.", "D." the "C" is the letter "C"; in "IC.", "C.", "CI." the "C" is a Roman 100.
- A "#" may be used in place of any numeral to continue a list. If the first item in a list is marked with "#", that list is numbered "1", "2", "3", etc.
- A list marker consisting of a single uppercase letter followed by a period (including Roman numerals like "I." or "V.") needs to be followed by at least two spaces (rationale).
All of the above are entirely compatible with how Pandoc works. There are two small differences with Pandoc's syntax:
- This plugin does not support list numbers enclosed in parentheses, as the Commonmark spec does not support these either for lists numbered with Arabic numerals.
- Pandoc does not allow any list to interrupt a paragraph. In the spirit of the Commonmark spec (which allows only lists starting with 1 to interrupt a paragraph), this plugins allows lists that start with "A", "a", "I" or "i" (i.e. all 'first numerals') to interrupt a paragraph. The same holds for the "#" generic numbered list item marker.
Configuration
All configuration options are put under a fancy_lists
key. You can
specify the configuration when creating your Environment
class:
use League\CommonMark\Environment\Environment; $environment = new Environment([ 'fancy_lists' => [ 'allow_ordinal' => true, // ... ], ]);
See the league/commonmark
documentation
about configuration for more details on how to specify configuration.
Supported configuration options:
-
allow_ordinal
- Whether to allow an ordinal indicator (º
) after the numeral, as occurs in e.g. legal documents (default:false
). If this option is enabled, input like1º. foo 2º. bar 3º. baz
will be converted to
<ol class="ordinal"> <li>foo</li> <li>bar</li> <li>baz</li> </ol>
You will need custom CSS to re-insert the ordinal indicator into the displayed output based on the
ordinal
class.Because the ordinal indicator is commonly confused with other characters like the degree symbol, these characters are tolerated and considered equivalent to the ordinal indicator.
-
allow_multi_letter
- Whether to allow multi-letter alphabetic numerals, to number lists beyond 26 (default:false
). If this option is enabled, input likeAA. foo AB. bar AC. baz
will be converted to
<ol type="A" start="27"> <li>foo</li> <li>bar</li> <li>baz</li> </ol>
Multi-letter alphabetic numerals can consist of at most 3 characters, which should be enough for a typical list. When a list starts with a numeral that can be both Roman or multi-letter alphabetic, like "II", it is considered to be Roman.
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).