Using <details> <summary> expandable content on GitHub with Markdown #details #summary #markdown #gfm #html

using-details-summary-github.md

How to use <details> <summary> expandable content on GitHub with Markdown

Firstly, what is <details> <summary>?

The HTML Details Element (<details>) creates a disclosure widget in which information is visible only when the widget is toggled into an "open" state. A summary or label can be provided using the <summary> element. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details.

Example

Toggle me!

Peek a boo!

<details><summary>Toggle me!</summary>Peek a boo!</details>

Is there a special GFM (GitHub Flavoured Markdown) syntax for using <details> <summary> on GitHub?
Answer: No, but you don't need it, since GFM allows embedding HTML inside Markdown.

Example

Shopping list

• Vegetables
• Fruits
• Fish

Code

#### Example

<details open>
<summary>Shopping list</summary>

* Vegetables
* Fruits
* Fish

</details>

Remember that blank lines are needed before/after a section of markdown that is within an html tag, otherwise the markdown won't work

More about details/summary

Browser support is good https://caniuse.com/#feat=details It falls back to being expanded all the time. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details

Similar gist https://gist.github.com/ericclemmons/b146fe5da72ca1f706b2ef72a20ac39d

It works for simple answers, but for longer README.md, the behavior is not consistent everywhere in every browsers.

Capture:

We have to pass an information such as Click to expand or why not an emoji like 👀, so it does render almost well everywhere.

<details>
<summary>👀
 
 ## Installation into *System*
</summary>

Make sure `./.local/bin` is sourced in your *PATH*

And run `./best_program.sh --install`

</details>

👀

Installation into System

Make sure ./.local/bin is sourced in your PATH

And run ./best_program.sh --install

LaTeX math blocks in details are buggy and only seem to work if there is no previous math on the page. For example:

<details>
<summary>Math</summary>

$$
1 + 1 = 2
$$
</details>

It works once:

Math

$$ 1 + 1 = 2 $$

But it doesn't work twice:

Math

$$
1 + 1 = 2
$$

Top-level math blocks still works:

$$ 1 + 1 = 2 $$

It doesn't seem to be a problem for other tags like <div>, just <details>.

The only workaround I've found is to use inline math, which always works in details:

Inline math

$1 + 1 = 2$

Inline math

$1 + 1 = 2$

Is there any workaround for the math blocks?

Ok, nevermind, I found a workaround for the math blocks. For some reason it works as long the whole block is put on one line with no spaces immediately after the first $$ in the math block. In my own gist, I can also put newlines in the math block as long as there are no spaces or newlines immediately after the first $$, but in this comment it seems it only works if it is entirely on one line.

<details>
<summary>Math</summary>

$$1 + 1 = 2$$
</details>

Math

$$1 + 1 = 2$$

Math

$$1 + 1 =2$$

Edit (2024-09-08): Looks like they broke the workaround, now math blocks get converted into inline math when you do this :(
Thankfully, fenced math blocks work:

Fenced math

$$1 + 1 = 2$$

Fenced math

$$1 + 1 = 2$$

How to prevent breaking when .md file is hosted on GitHub pages?