Using `<details>` with GFM and kramdown/Jekyll

Posted:2024-01-07, Updated:2024-01-25
Tags:Jekyll,kramdown

The <details> tag is a useful addition that came with HTML5, but markdown inside of a <details> tag is treated differently by GitHub and kramdown (which is used by Jekyll).

For GitHub
For kramdown / Jekyll
Source Documents

For GitHub

GitHub just needs blank lines between any markdown that should be parsed and the <details>, <summary>, or </details> tags:

<details><summary>A summary of the contents.</summary>

- a markdown
- list to parse

</details>

For kramdown / Jekyll

The <details> tag is a block element and by default kramdown does not parse markdown inside of HTML block elements. Parsing can be enabled in three different ways.

For a specific block element

Add the attribute markdown="1" to the element:

<details markdown="1"><summary>A summary of the contents.</summary>
Some **longer** and more *detailed* contents that includes markdown...
</details>

For a whole markdown file

Add parse_block_html: true to the kramdown: options in the file’s front matter:

---
title: Some Title
kramdown: 
  parse_block_html: true
---

For all documents on a Jekyll site

Add parse_block_html: true to the kramdown: options in _config.yml:

markdown: kramdown

kramdown: 
  parse_block_html: true