Skip to content

Instantly share code, notes, and snippets.

@scmx
Last active September 28, 2024 18:16
Show Gist options
  • Save scmx/eca72d44afee0113ceb0349dd54a84a2 to your computer and use it in GitHub Desktop.
Save scmx/eca72d44afee0113ceb0349dd54a84a2 to your computer and use it in GitHub Desktop.
Using <details> <summary> expandable content on GitHub with Markdown #details #summary #markdown #gfm #html

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

@benburrill
Copy link

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?

@benburrill
Copy link

benburrill commented Apr 25, 2024

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

@dragontheory
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment