Markdown Help and Hints

learn-markdown

#1

Markdown Tips

Much of this comes from the Stack Exchange Markdown page. Other good places to look are:

The point of Markdown is that it is designed to look somewhat like the formatting that it implies. You might already think to surround something with asterisks to make it stand out; in Markdown, that will make it italicized.

Headings

# Use more #s to make subheads
## this would be a sub-head

Another way to make headings is to put === or — in the line under the heading.

This is a heading
===
This is a subheading
----

But wait! If you put a blank line before the — you will instead get a horizontal rule. (You probably call it a line.)


Linebreaks

A blank line between two lines makes a new paragraph.

End a line with two blanks to make a new line  

Italics, Bold, and strikethrough

Sure you can use the editor’s icons or shortcuts (like control-B to bold), but you can also just do the following:

*This is italicized*, and so is _this_.
**This is bold**, and so is __this__.
Use ***italics and bold together*** if you ___have to___.
It can be fun to --strikethrough-- text. (That's two dashes).

Lists

You can choose pretty much any character that seems like it would work as a way to start an item in a list, stick a * - or a + at the start of a line, and lo! It is a list. If the first item in a list is a number, the rest of the list will be numbered as well. Some versions of Markdown will let you start a list at an arbitrary number if the list starts with something other than 1. Discourse does not do that right now, so

3. Item
- another item
+ the last item

will look like this:

  1. Item
  • another item
  • the last item

To have sub-items in a list, you simply indent the sub-items. Markdown just “gets” it.

Links

There are three ways to write links. Each is easier to read than the last:

Here's an inline link to [Google](http://www.google.com/).
Here's a reference-style link to [Google][1].
Here's a very readable link to [Yahoo!][yahoo].

[1]: http://www.google.com/
[yahoo]: http://www.yahoo.com/

Links can have a title attribute, which will show up on hover. Title attributes can also be added; they are helpful if the link itself is not descriptive enough to tell users where they’re going, or if you want to add something subtly humorous.

Here's a <span class="hi">[poorly-named link](http://www.google.com/ "Google")</span>.
Never write "[click here][^2]".
Visit [us][web].
[^2]: http://www.w3.org/QA/Tips/noClickHere
      (Advice against the phrase "click here")
[web]: http://superuser.com/ "Super User"

Special links

There are a few kinds of special links.

Users

If you are referring to someone, rather than mention them by name, you should instead type a @ and then start typing their username. This will give you a list of names to choose from. When you refer to someone with their name (like @pfaffman) not only does it make a clickable link to their profile, but also that user will get a notification. If you just type a name without the @, that user might not notice that you referred to them.

Topics

You can refer to a topic by typing a #. Like with @, Discourse will suggest topics as you type. Here is an example: #quests.

I think that there should be a way to do this for tags, but I can’t find it. If you do, let me know!

Oneboxes

There are certain web sites that this instance of Discourse knows how to treat specially. For these, you just put the URL on a line by itself. Sticking a URL inline will make it clickable https://www.youtube.com/watch?v=6A5EpqqDOdk, but putting it on a line by itself will embed the youtube video on the page, like this:

Other sites that this works for include wordpress.com, Amazon, and some others. If you are linking to something that would make sense to be embedded, you might see what happens if you paste the URL on a line by itself.

Spoilers

Sometimes it is useful or fun to be able to hide text from someone. The spoiler tag will let you do that.

[spoiler]Hello **Discourse** peeps![/spoiler]

It works only for short things, though, complicated formatting gets lost in that kind of spoiler. Another way to accomplish the same is the HTML details tag. It works like this:

<details>
<summary>the summary</summary>
blablabla
</details>

Polls

You can make a poll in any post or reply. It works like this:

What do you think about polls?
[poll name=examplePoll type=multiple]
 - Polls are useful.
 - Polls are pointless.
 - I like tacos.
[/poll]

DOIs

This is not a standard in Markdown or Discourse, but I wrote a little Discourse plugin that will make a DOI (e.g., 10.1007/s11528-007-0040-x ) into a link.