Notes to Future-Me

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

Posted:2024-01-07, Updated:2024-01-25

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

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


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

For a whole markdown file

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

title: Some Title
  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

  parse_block_html: true

Source Documents