Markdown spoilers

JoshyPHP

Hello everyone!

This is a request for comments as well as a heads-up about an upcoming addition to the Markdown syntax in Flarum. If you have any comments, leave them here and I'll read everything. If you have nothing to add but you like the idea, you can also like this post and move on with your day. 🙂

First a bit of context: I'm the author of the text-formatting library used by Flarum. It handles all of the markup, including BBCodes and Markdown-style formatting, and enables Flarum extensions to add their own markup and features such as mentions or custom BBCodes. Changes to the core plugins automatically trickle down into Flarum. The plugin in charge of the Markdown syntax is named Litedown, and the name is used interchangeably to describe the plugin and the syntax of this Markdown flavour. The syntax itself is based off the original Markdown syntax and tries to support the most commonly requested/used extensions to the syntax. Which brings me to spoilers.

One of the most requested markup in forum software is spoilers. When they are not supported out of the box, they are usually added one way or another via an extension or via a user hack. Most of the time, spoilers can be created with a custom BBCode. Unfortunately, there is no consensus over a Markdown-like syntax for spoilers:

StackExchange has supported block spoilers for a few years. They start with >!
Reddit added inline spoilers earlier this year. They use >! and !<
Discord added inline spoilers earlier this year. They use || and ||

This is what they look like:

>! This is a block spoiler using StackOverflow's syntax.  
>  You're still inside the spoiler because only the first marker matters, unlike StackOverflow's syntax.

- Here's an >!inline spoiler!< using Reddit's syntax.
- Here's an ||inline spoiler|| using Discord's syntax.

Other than those three, GitHub and GitLab have chosen not to add a syntax for Markdown spoilers and instead enabled the <details> and <summary> HTML elements. Other websites and other Markdown flavours have discussed adding spoilers without coming to a decision.

I intend to add support for spoilers in the Litedown plugin in version 2.1 of the library. Currently, my intention is to support the three forms shown above. I think the block spoiler syntax makes a lot of sense. It looks and behaves like the normal quote syntax and it just works. Reddit's inline spoilers are a variation on that syntax and I think it fits nicely with the rest. I don't like Discord's syntax because the same marker is used to open and close the spoiler, and because programmers associate the double pipes with the boolean "OR". However, Discord is a popular app and users familiar with Discord may expect those spoilers to work in other Markdown-enabled text editors.

The implementation is ready, the new feature has virtually no effect on performance or software complexity, and I expect it to be fully compatible with existing spoiler extensions. I have looked at @Kvothe's extension and @sijad's extension and they should be fully compatible. The [spoiler] BBCode's behaviour won't change and Markdown-style spoilers will match their BBCode counterpart.

You can try out the online demo here. The default style is very simple and may change slightly in the final version but if you want cool-looking spoilers you'll have to install an extension.

Similar implementations:

Other implementations:

https://github.com/NicolasSiver/nodebb-plugin-ns-spoiler

Other discussions:

Pollux

JoshyPHP First a bit of context: I'm the author of the text-formatting library used by Flarum. It handles all of the markup, including BBCodes and Markdown-style formatting, and enables Flarum extensions to add their own markup and features such as mentions or custom BBCodes. Changes to the core plugins automatically trickle down into Flarum. The plugin in charge of the Markdown syntax is named Litedown, and the name is used interchangeably to describe the plugin and the syntax of this Markdown flavour. The syntax itself is based off the original Markdown syntax and tries to support the most commonly requested/used extensions to the syntax.

I understand, that this thread is about spoilers. I want to ask nevertheless:

Are there any chances to fix some of the basic shortcomings like missing subset and underline tags in Markdown / Litedown (and no, BBCode is not an option for me). Would it be worth to start a separate discussion for that?

JoshyPHP

I wasn't sure how to tag the thread so I went with "Feedback" and "RFC".

luceos

I completely agree with your decision. I also dislike the discord version, it seems off. The stack overflow and reddit versions would probably be easiest for me to remember.

Kayo

There's also the @010101 extension big beautiful bb code that give us pop up and accordeon spoiler types.

010101

Kayo Thanks for the shout out.

For a really easy to use spoiler, I would agree with going with Reddit's syntax. And, markdown is faster to type than bbcode. But, if anyone likes my accordion bbcode and thinks of a better naming convention / syntax, let me know. I've been thinking about creating shorter versions of all the bbcodes in my extension. So, instead of having to type out [accordion], maybe there could be a short version as well... something like, [ac] or [acrd] ? Same with the tooltip, a version which is simply, "tp" could be added versus typing out "tooltip"... saves a few keystrokes.

Anyway, sorry, I kinda hijacked this thread a bit. Just thinking out loud... Go with Reddit's version for this! 😀

Oh, another related note. My biggest beef with both markdown and bbcode is if you don't know it, especially with custom bbcodes, you have to look up how to do it. The latest editor Flarum uses at least solves this for the basics like bold, italics, link, and so on. But, I wonder if I can figure out how to add a button to the editor (similar to the emoji button) and then a list of bbcode and/or markdown pops up. That'd be sweet.

jordanjay29

I definitely like the block and reddit inline spoilers, those are really easy to use. Discord's syntax is really naive, IMHO, because that prohibits multiple | characters in a row without hiding some of them. Even though something similar can occur with * characters in markdown, those have been conventionally used for emphasis far longer than markdown has existed and emphasis is what they activate, so it's more intuitive. Spoiler codes, like urls in markdown, have to be learned so it makes sense to use something that would never be utilized in that way otherwise.

JoshyPHP

Yeah, the Discord syntax is unfortunate. My guess is whoever decided on double pipes was influenced by the iOS keyboard and the vertical markers used to select text and delineate the spoiler.

JoshyPHP

010101 So, instead of having to type out [accordion], maybe there could be a short version as well... something like, [ac] or [acrd]

That'd be better handled at the editor level, either with custom buttons or maybe even autocomplete. I don't know what autocomplete library Flarum uses for mentions (or is it homebrewed?) but some of the existing libraries can offer multiple sources/triggers. One could be triggered by [ and offer a list of BBCode names.

Remember that if you were to replace your [accordion] BBCode, it would stop working in old posts. Instead, you could create an new alias for it but as I mentioned that's something that'd be better handled as a UI improvement. Regardless, here's how you could create an alias:

$bbcode                   = $configurator->BBCodes->add('ac');
$bbcode->tagName          = 'accordion';
$bbcode->defaultAttribute = 'header';

010101

JoshyPHP Oh man, you just opened a whole new world. Yes, one day, to be able to have bbcode auto complete in Flarum... That. Would. Be. Amazing. 🤔

phi

Markdown works well for spoilers for me, it just shows "Details" when nix expanded and I didn't find an option to change that.
Is there an option to provide a summary for a spoiler with markdown?

enricodx

Is there a way to change the default label of spoiler?

Ralkage

enricodx this has been discussed before, but unfortunately no, this isn't supported 🙁

TextFormatter's Litedown plugin supports Markdown-like syntax; we have separate extensions that tackle missing syntax such as tables, checklists, etc supported by TextFormatter through plugins.

Though, that doesn't stop someone from creating an extension themselves to override the spoiler syntax in order to add an optional title 😉

ctml

enricodx

Ralkage Though, that doesn't stop someone from creating an extension themselves to override the spoiler syntax in order to add an optional title

Like this? 😃

https://discuss.flarum.org/d/26366-flarumite-simple-spoilers-pure-html5-and-css

Arnold

enricodx you can do that with this extension: https://discuss.flarum.org/d/18796-friendsofflarum-bbcode-details

Like this:

[details title="Title goes here"][/details]

TB54

(I believe the spoiler button is linked to the markdown extension so I post it here, but maybe I'm mistaken ?)

Just a little suggestion (and it's totally subjective) in case of future updates, but a fade to reveal the spoiler text, like on reddit, would be a nice detail to add, and more clear for a newbie. I tried to manage it with a css transition, but I realized it's a script removing the class, not changing it.