Hiding details and editorial comments

Documentation & Support Forum
1

This topic is a linked part of a larger work: “Discourse Website Manual for edgeryders.eu”

 

Documents the options in the Discourse software for hiding various content elements from the viewer, and our conventions in applying these.

Content

1. Paragraph with hidden details (using BBCode)

2. Paragraph with hidden details (using HTML)

3. Inline text with hidden details

4. Hidden editorial comments

1. Using BBCode: Paragraph with hidden details

1.1. In normal text

The following code allows the user to click on the paragraph to see additional details unfolding. It only works with full paragraphs though, means you cannot embed the element inline into normal text.

The code can also be inserted from the Discourse editor by clicking the options button :gear: and then on “Hide Details”.

Example:

[details="spoiler alert"]
it's a **sled**

> And there is a quote inside.
[/details]

Result:

spoiler alert

it’s a sled

And there is a quote inside.

As you see, further formatting of the hidden details is possible, including the use of code sections, quotes etc… But formatting the summary text is not possible (it was, though, in a previous version of Discourse). If you require that functionality, please use HTML to hide details.

You can separate the opening BBCode tag [details="…"], the content and the closing tag [/details] with line breaks. Or you can put everything into a single line. You can not, however, mix these two techniques.

1.2. In a quotation

You can use the “Hide Details” element inside a quotation section.

Example:

> [details="spoiler alert"]
> it's a **sled**
> [/details]

Result:

spoiler alert

it’s a sled

1.3. In list items

You can use the “Hide Details” element in list items. (It did not work properly in older versions of Discourse due to bugs, though.)

Example:

* [details="Summary"]
  This text will be hidden
  [/details]

Result:

  • Summary

    This text will be hidden

This is documented in much detail in “Formatting text content: 4. Details about lists”. Including templates for lists with multiple levels of folding.

1.4. In tables

It not possible to use the “Hide Details” element in Markdown tables. The “Hide Details” BBCode tag can be used in HTML tables, but this is a buggy feature right now. Better use HTML to hide details in such a case.

Example:

<table>
  <tr>
    <td>1</td>
    <td>2</td>
  </tr>
  <tr>
    <td>3</td>
    <td>

[details="4"]
5! 6! 7! 
8! 9! 10!
[/details]
</td>
  </tr>
</table>

Result:

1 2
3
4

5! 6! 7!
8! 9! 10!

2. Paragraph with hidden details (using HTML)

You can use a HTML tag to achieve the same result as with the [details="…"]…[/details] BBCode tag.

Example:

<details>
    <summary>Summary Text</summary>
    Hidden Details Text
</details>

Result:

Summary Text Hidden Details Text

This has several advantages over the BBCode version:

  • It works in HTML tables without any issues.
  • The summary text can be formatted as well, using additional HTML tags.
  • You can set the initial state so that the details are shown by writing <details open>…</details>.

3. Inline text with hidden details

This uses a HTML link element with a title attribute, showing the hidden details when hovering over that link. By convention, we use the :speech_balloon: emoji to mark the special role of such a link. The hidden details can only be pure text, but the element can be placed anywhere inside normal text just like a regular hyperlink. Example:

Example code with <a title="More details are here!">more 
details :speech_balloon:</a>.

Example code with more details :speech_balloon:.

4. Hidden editorial comments

This method will completely hide text from the reader, but show it in the “source code” of the post when opening it for editing. This makes it suitable for editorial remarks, such as markers for to-do items in a text.

This works by using normal HTML comments, such as the following:

Normal text <!-- TODO: Make the normal text more crazy. --> and 
more normal text.

Like every HTML comment, text hidden with this method is visible to everyone who can see the topic, by using the browser’s Inspector mode (“right click → Inspect”). This means, do not use it to keep information private, only to hide text for cosmetic reasons.

The above also shows our convention for to-do markers: prefixing the text with TODO:. This allows to find to-do items quickly by searching for that prefix in the text.

1 Like