Formatting quick reference guide

010101

Flarum post formatting guide for your forum

Code: https://github.com/zerosonesfun/flarum-formatting-guide
Example: https://www.sitbreathe.be/d/70-formatting
Suggestion: Use the beginning two paragraphs in a help pop up or something and then link to the rest of the guide.
Blog: https://www.wilcosky.com/d/2-flarum-formatting-guide
Implementing the pop up overlay suggestion:

Original post/idea:

Unless someone replies here telling me this exists, and as long as nothing crazy happens, I plan on sitting down and creating Flarum formatting instructions. You know, for folks who may not be comfortable with markdown or BBcode.

I’m going to make it really nice with screenshots of the toolbar. Or, maybe I’ll make one with and one without screenshots in case someone wants text only instructions for their users.

I’ll also try to make it as brief as possible so that it could fit in a pop up for example. Or, maybe a brief and long version. We’ll see what I come up with.

tolgaaaltas

010101 When i had a Flarum based website, i used (of course i gave reference) Pretpark.club's FAQ guide and translated into Turkish. It's simple and understandable but it requires FoF Formatting and FoF Upload.

clarkwinkelmann

There is this 2016 discussion which might be a bit outdated https://discuss.flarum.org/d/2991-how-to-use-markdown-and-bbcodes

TextFormatter documentation also includes a list of examples:

https://s9etextformatter.readthedocs.io/Plugins/BBCodes/Add_from_the_repository/#list-of-bundled-bbcodes
https://s9etextformatter.readthedocs.io/Plugins/Litedown/Syntax/

But probably not all bbcode in TextFormatter documentation are enabled by default in Flarum.

010101

I was over thinking this. I think if a user has never seen markdown before (or BBcode), something like the below works in combination with the handy toolbar.

This only lists some of the extremely common options (bold, italics, etc.) and is very brief because I envision this being in a handy pop up.

The “more” at the end of each paragraph could link to the full documentation.

Use Markdown or BBcode to add formatting. The toolbar will help you add common Markdown which involves adding certain special characters in front of or around your text, such as: **bold**, *italics*, ~~strike~~, >!spoiler!<, [link text](url), ![alt text](image url), more.

BBcode is a common bracket style code that wraps your text, such as: [b]bold[/b], [i]italics[/i], [s]strike[/s], [url=]link text[/url], [img]url[/img], more.

It’s hard to imagine users not knowing what markdown or BBcode is, but I’m sure there’s a lot of folks who don’t. It depends on the forum’s target audience.

clarkwinkelmann

bold is **bold** or __bold__ while italics is *italics* or _italics_ (it's the number of asterisks or underscores that counts 😉 )

010101

clarkwinkelmann Turns out I need some sort of helper guide too. 😳

010101

Turns out this was easier than I thought. I just needed to grab this https://github.com/s9e/TextFormatter/edit/master/docs/Plugins/Litedown/Syntax.md and now all that is left is cleaning it up a bit. Then I'll do the same for the BBCode but only include the core ones Flarum's BBCode extension includes.

Work in progress: https://www.sitbreathe.be/d/70-formatting

010101

There could be an issue with the [list] BBCode, unless I'm doing it wrong.

one
two
where's the bullet point?

How are you supposed to do it? Is this right or wrong?

[list]
one
two
where's the bullet point?
[/list]

And then only at my forum, unordered markdown lists aren't working.

interesting
ok
they work here

Probably an extension conflict I would guess...

clarkwinkelmann

010101

[list]
[*]item 1[/*]
[*]item 2[/*]
[/list]

item 1
item 2

Seems like having both Markdown and bbcode enabled causes to have <p>s inside of <li>s 😅 which is why there is so much space between the items.

010101

clarkwinkelmann Thanks! I very rarely make lists with BBCode.

clarkwinkelmann

010101 me too! I had to check the documentation for [*]

Markdown lists are just so much nicer. Markdown is so much more "intuitive" in its markup.

010101

Here’s a solution so that users can at least reference a few common formatting options anytime. Go to the codepen page below and copy/paste the html tab and the JavaScript tab into your custom footer in your Appearance settings. Then copy/paste the CSS into your custom CSS. Just in case you have little to no coding experience, for the JavaScript, don’t forget to wrap it in <script></script> tags. Edit the text if needed (at the very least the “learn more” link).

To see what you’ll get click the light grey circle/question mark in the bottom right of the white box below (if on mobile click the “result” button first):

010101

I might try to make this an extension. I assume the footer extension that’s out there would work with some HTML and CSS changes. Actually, maybe the footer extension as-is would work with nothing but CSS changes. 🤔

Then again, a simple link to a help page works too so I’m not sure extensionifying this would be worth it.

010101

Ok, I decided not to make this an extension because a similar extension exists and I don't want to maintain a new extension right now. But, even if you have zero coding experience you'll be able to get this working at your Flarum by following the steps in the image below. What's nice is you can use this for anything... a help guide, or you can use it as an extra menu by adding links to things like your privacy policy and/or contact form. And, as you'll see it's very little code (lightweight).

Once implemented, it's as easy to update as a real extension with settings. You just go back to your custom footer and edit the text. I also just added a few HTML comments to the code on codepen so that you know exactly where to edit. Enjoy! 🙂