Support use of CommonMark
- Dominant language
- PHP
- Stars
- 15.7k
- Forks
- 1.4k
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 13
Description
Given the inconsistencies in the current markdown parsers, and the attempt to formalise the specification and fix/avoids bugs in those parsers, it would be good to support the formal specification.
For example:
Consider a page consists of the continuation of a list:
```
4. foo
* test
* test
5. bar
* test
* test
```
This renders "incorrectly" on github as follows:
1. foo (< shows 1 on github)
- test
- test
1. bar (< shows 1 on github)
- test
- test
At the moment, in it's current form, it's impossible to render this nicely - looking at http://commonmark.org/ and the history, there was never a proper specification for Markdown. The commonmark group of people are apparently trying to formalize this specification.
Looking at the proposed formal specification for the example above, the expected behaviour is to add a "start=3" element to the HTML output as shown at http://spec.commonmark.org/0.21/#lists. For a non-technical user, this would appear to be more appropriate behaviour then the current behaviour within parsedown.
Putting the example above into a comparision tool @ http://johnmacfarlane.net/babelmark2/?text=4.+foo%0A%0A*+test%0A*+test%0A%0A5.+bar%0A%0A*+test+%0A*+test - the various markdown parsers have different behaviour. For this particular example, 5 parsers appear to give output that would be most similar to what an end user might expect for this case:
commonmark 0.21.0
cheapskate 0.1.0.1
league/commonmark 0.12.0
markdown-it 4.1.0
pandoc
league/commonmark is the only php parser within this list, and has an optional twig rendered - https://github.com/webuni/commonmark-twig-renderer - which could be used to allow someone to specify how a block is rendered e.g. for a strong markdown block:
```
{% block strong -%}
{{ block('_inline_children') }}
{%- endblock %}
```
This could allow a user/theme author to easily add a CSS class tag to generated HTML from markdown content, or otherwise adjust HTML output.
Contributor guide
Research direction
Start by locating Grav’s current Markdown parser integration and compare the supplied list example with the CommonMark 0.21 specification and Babelmark2 results. Clarify whether the goal is parser replacement, CommonMark compatibility, or configurable HTML rendering; done should include agreed behavior for the example and corresponding validation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, php
- Domain
- content
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100