Hiding details and editorial comments

subtopic

#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. Full paragraph with hidden details

2. List item with hidden details

3. Inline text with hidden details

4. Text with hidden editorial comments

1. Full paragraph with hidden details

The following code allows the user to click on the paragraph to see the details unfolding. It only works with full paragraphs though, means you cannot embed the element in normal text. On the upside, further formatting inside the hidden details is possible.

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

As a result, you will see the following:

hidden details / spoiler alert

it’s a sled

You can format the summary text, but only using HTML. Example:

[details=<b>hidden details / spoiler alert</b>]it's a **sled**[/details]
<b>hidden details / spoiler alert</b>

it’s a sled

2. List items with hidden details

In our current version of Discourse (admittedly not the newest), the [details=…]…[/details] feature does not mix with Markdown list features. As a result, a leading * or 1. cannot be used to put it into a list item, and leading whitespace cannot be used to determine the list level of a paragraph. Also, it cannot be wrapped into quote formatting with >.

However, HTML comes to the rescue:

  • Use a <ul> … </ul> around the element once or more to give it the right an indentation level for alignment to an unordered list to which it logically belongs:
    [details=hidden details / spoiler alert]it's a **sled**[/details]
    This closes the Markdown list context, so use `
    ` also for the indentation level of paragraphs immediately below (like this one). You will have to start a new list item before you can again use leading spaces to determine the indentation level of paragraphs.
  • Use <blockquote> … </blockquote> around the element to put it into a quote box:
    [details=hidden details / spoiler alert]it's a **sled**[/details]
  • To integrate the [details=…]…[/details] into ordered lists, create the whole list as a HTML <ol> … </ol> list. Just using <ol> … </ol> for the indentation level of the details element does not work, as it ends the Markdown list context so that following list items start again with “1.”. (Which does not matter of course if the details element is at the very end of a list.)

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. Text with 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.