How to make "spoiler" text in GitHub wiki pages?

html

collapsible-content

github-wiki

spoiler-effect

byNikita Barsukov·Oct 9, 2024

Create a collapsible spoiler section in GitHub wikis using HTML:

<details>
  <summary>Click to unveil the hidden truth!!!</summary>
  <!-- Don't worry, it's not the truth about Santa Claus -->
  <p>The big spoiler text lives here, happily hidden from prying eyes.</p>
</details>

To present the spoiler, click on the summary.

Understanding Usage of Details & Summary Tags

HTML's <details> and <summary> tags are the heart of crafting collapsible content in GitHub wikis. As GitHub Flavored Markdown (GFM) supports HTML tags, these work smoothly.

Are all browsers playing along?

Modern web browsers support the <details> tag. But if your users have love for older, nostalgic browsers, <details> may not work. Be a good friend and put a disclaimer in your wiki.

Exploring Other Languages beyond GFM

GitHub wikis happily support AsciiDoc and RST (reStructuredText). In case you hit with the limitations of GFM and HTML, these could be the lifeboats to save you.

The Art of Nesting Tags

To maintain a tidy and organized nested spoiler structure, it's crucial to properly indent within <details>:

<details>
  <summary>Main spoiler</summary>
  <!-- He lies, he cheats, he is... -->
  <p>The main secret</p>
  <details>
    <summary>Just another spoiler</summary>
    <!-- Sequels are often disappointing, aren't they? -->
    <p>The hidden secret's secret.</p>
  </details>
</details>

And yes, it's not just a markdown thing, an empty line after </summary> is crucial in some parsers for correct formatting.

HTML vs Markdown in Summary Tag

Within the <summary> tag, HTML is your real friend. Markdown might just sit there and do nothing.

Going Beyond the Basics

For advanced formatting, use the <p> tag within <details>. It can help maintain a consistent look and feel for hidden content.

Creating Spoiler Effects with CSS

CSS is the stylist to your content created by HTML. You can style your spoilers with specific CSS classes.

CSS Spoiler Pattern

A CSS pattern for spoilers is to use the following structure:

[hidden text droppin' some truth bombs](#spoiler)

Then apply your styles for a[href="#spoiler"] and a[href="#spoiler"]::after to the CSS part:

a[href="#spoiler"] {
  background-color: black;
  color: black;
  text-decoration: none;
  /* We are trying the Ninja mode here, stealth is key */
}
a[href="#spoiler"]:hover,
a[href="#spoiler"]:focus {
  color: white;
  /* Surprise!!!! There was a ninja text here all along!!! */
}

Don't forget, CSS tricks work best on **GitHub Pages or projects with editable CSS. On wiki pages, stick with the trusted HTML <details> tag.

Making the Use of Images

Screenshots or diagrams are a great way to visualize the workings of your collapsibles. Just be sure they are properly nested within <details> tags to keep the spoiler effect.

Learning Asciidoc and RST for Complex Tasks

For heavier formatting tasks, AsciiDoc and RST could be the magic wands you are looking for. These provide broader features than Markdown and are supported by GitHub wikis.

They can be lifesavers when: