cebe
Inline HTML support with <details> and <summary> in Github flavored markdown
<details> and <summary> are tags introduced in HTML5 as a way to enclose collapsible / expandable widgets. Both Github and Gitlab support using them as inline HTML. And they are parsed and displayed properly. Moreover, markdown tags within them are parsed correctly.
People uses them to enclose less important information, such as advanced examples. And by using them, the display of README.md are much easier to read.
Please check the below example. This library does not give the same result parsing the code the same way Github does:
Example
Markdown
<details open=true><summary>Some PHP example (expanded)</summary>
```php <?php
// this is a comment echo "hello world";
?> ```
</details>
<details><summary>Some PHP example (collapsed)</summary>
```php <?php
// this is a comment echo "hello world";
?> ```
</details>
Parsed result on Github
Some PHP example (expanded)
<?php
// this is a comment
echo "hello world";
?>
Some PHP example (collapsed)
<?php
// this is a comment
echo "hello world";
?>
Real-life example: Same README on different platforms
- https://gitlab.com/phata/hook/blob/v1.x/README.md
- https://packagist.org/packages/phata/hook
composer/packagist#974 has fixed the problem displaying the HTML tags <summary> and <details>. But the markdown within the tag is not parsed normally. I'm not sure if it is caused by this library, or how Packagist is using it.
As reported in composer/packagist#978, @Seldaek pointed out it is likely to be a problem in the markdown library. Quote:
I saw that but I believe it's the markdown parser at fault as the backticks remain in the output. So I figured your issue there was covering it already and decided to close on our side.
See http://johnmacfarlane.net/babelmark2/?normalize=1&text=%3Cdetails%3E%3Csummary%3ESome+PHP+example+(collapsed)%3C%2Fsummary%3E%0A%0A%60%60%60php%0A%3C%3Fphp%0A%0A%2F%2F+this+is+a+comment%0Aecho+%22hello+world%22%3B%0A%0A%3F%3E%0A%60%60%60%0A%0A%3C%2Fdetails%3E for a comparison of the different markdown parsers for that input.
But the markdown within the tag is not parsed normally. I'm not sure if it is caused by this library, or how Packagist is using it.
This is expected because markdown is not parsed inside HTML blocks.
https://daringfireball.net/projects/markdown/syntax#html Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style emphasis inside an HTML block.
As github is doing it we might add that feature to the GithubMarkdown class.
Btw, I was not aware that packagist is using this library :)
@cebe CommonMark (which GFM is based on now) defines that it is processed if there are empty lines between the HTML markup and the Markdown markup (which probably means it does not require balanced tags in the HTML blocks, and so the empty line makes the structure be HTML > MD > HTML instead of just HTML, but I haven't checked in the spec).
See http://johnmacfarlane.net/babelmark2/?normalize=1&text=%3Cdetails%3E%3Csummary%3ESome+PHP+example+(collapsed)%3C%2Fsummary%3E%0A%60%60%60php%0A%3C%3Fphp%0A%0A%2F%2F+this+is+a+comment%0Aecho+%22hello+world%22%3B%0A%0A%3F%3E%0A%60%60%60%0A%3C%2Fdetails%3E for the similar input without the empty lines. commonmark.js will not parse the codeblock anymore in that case.