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
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 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 |
45! 6! 7! |
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 TextThis 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 .
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.