Guide: Write cool posts and comments with Markdown for newbies
Hey everyone, I figured that some new users might not know that comments and posts have a formatting standard called Markdown.
In simple terms, Markdown is a (semi)universal language that uses formatting symbols to give a certain style to a portion of text.
This quick guide can help you to write in a way that's more appealing and easy to read.
FORMATTING
SYNTAX
EXAMPLE
New line
put two spaces at the end of the line you want to break
Line__
New paragraph
return two times at the end of the paragraph
Line↵↵
Horizontal rule
between each paragraph put three "-" or "*"
***
Bold
put your text between two "**" or "__"
**Bold** or __Bold__
Italic
put your text between two "*" or "_"
*Italic* or _Italic_
Subscript
put your text between two "~"
~Subscript~
Superscript
put your text between two "^"
^Superscript^
Inline code
put your text between two "`"
`sudo rm -rf /`
Headings and Titles
put one or more "#" at the beginning of the line
# Headings for level 1, ## Headings for level 2...
You can also do unordered lists using "-" at the beginning of each line:
- Salt
- Potatoes
- Beans
will become
Salt
Potatoes
Beans
Or ordered list by putting "1." at the beginning of each line:
1. Salt
2. Potatoes
3. Beans
will become
Salt
Potatoes
Beans
You can save other users from spoilers by encasing a paragraph between a section that starts with ":::" followed by a space and the word "spoiler" + the title of the spoiler and ends with ":::". The spoiler will be hidden inside a menu and you'll be able to see it if you click on it
::: spoiler warning! spoiler!
the butler did it
:::
will become
warning! spoiler!
the butler did it
In the end you can also format big code blocks by putting "```" at the beginning and at the end of each paragraph
```
println("Hello World!")
```
will become
println("Hello World!")
Last but not least remember that you can always use break formatting syntax by putting "\" in front of a character:
so if I want "^" in my text without having the rest of the paragraph in superscript, I'm simply going to write "\^"
Markdown is notoriously understandized, so there are lots of unofficial extensions. This is a major downside of markdown, as you cannot trust a renderer to properly show the formatting beyond the basics.
It's still really nice, because of two great features:
it's super easy to learn. Just look at a few examples and off you go.
even when it's not rendered, it's still easy to read (which I think contributes to making it easy to learn).
The Markdown will be passed in the ActivityPub messages in plaintext, so it's up to the app developer how to interpret the Markdown. Looks like someone already created a ticket on GitHub so I'd recommend either adding a thumbs up to increase visibility or make the change yourself if you're able!