Site Notes

Guide to Comment Formatting

By Ryan Danks
Published December 14, 2009

Among the new features RTH has implemented on the site is the addition of Markdown to the posting system for registered users.

Markdown is a software tool that allows commenters more control over how their posts get displayed on the web to improve readability, without the user having to use the awkward HTML markup system that can make the original text difficult to read.

To use Markdown, you simply add certain character combinations (which I'll call "tags") to tell the website how you want your text displayed. Before your post is displayed, Markdown looks through your post for the tags and automatically converts the text and tags combination to HTML that your browser can understand.

If you don't want to bother formatting your post, just enter the text as you always have. If there are no Markdown flags in the text then it will not be changed and it will be posted in plain text like always.

I'll now cover the basic syntax of Markdown element by element. A full description of the entire syntax can be found here if you're curious.

Span Elements

These elements are used to format text the way we would in an email or other document. They allow us to add emphasis to words, use special characters or create words that link to other websites.

Emphasis

To add emphasis to a word or group of words, simply wrap what you want emphasized in asterisks. One asterisk will italicize the word(s) and 2 will bold them. Underscores can also be used in place of asterisks. One thing to note is that due to how Markdown was implemented on RTH, users can not bold or italicize within a word if you use the underscore, (eg. un*freaking*believable works but un_freaking_believable won't) though on some other implementations it is possible.

Another way to add emphasis is using a "Code Span". A code span is text that is wrapped on either side with a backtick character (`). Markdown will treat any text inside the two backticks as computer code and thus will not apply any formatting to it, aside from changing the font to a different "terminal" style font.

This is useful when you need to display Markdown's own syntax (like I've done throughout this document) or the syntax from other computer coding languages. Its also a quick way to prevent Markdown from reformatting your text should you accidentally include a tag or character that Markdown uses for special purposes.

Input:

*italic* **bold**
*italic phrase* **bold phrase**
`This is a code span`

Output:

italic bold
italic phrase bold phrase
This is a code span

Special Characters and the Escape Character

Another nice feature of Markdown is the ability to easily enter non-standard characters into your text. This includes everything from non English letters (û) to mathematical (²) and logical (?) symbols. All you need to do is enter the HTML standard code for the symbol and Markdown will translate it to the correct character and display it with your text.

As you can see from the link, each character code is of the form &#(number); with the more common codes also having a second code of the form &(desc); with (desc) being a short descriptor of the symbol (eg. the copyright symbol is © or ©).

Input:

E=mc²
It cost €1.57 in Italy.

Output:

E=mc²
It cost €1.57 in Italy.

The other special character I want to mention is the backslash (\) character. The backslash is known as an Escape Character and it's used whenever you need to use the literal intention of a character that Markdown uses for a special purpose.

The backslash must precede any of the following characters if they are used in a fashion similar to how Markdown uses them ( ` * _ { } [ ] ( ) # + - . ! ) The Code Span emphasis mentioned above can also act as an Escape Character since it too ensures the literal interpretation of your text, that is if you don't mind the font of your text changing.

Input:

*Markup's Interpretation*
\*Literal Interpretation\*
`*Also Literal Interpretation but with code style output*`

Output:

Markup's Interpretation
*Literal Interpretation*
*Also Literal Interpretation but with code style output*

Links

These tags allow us to hyperlink text directly to a website, and Markdown gives us two ways to do this. The first is what's called an "inline link" and is more suitable for linking to a website only once. The second is "reference linking" and is more useful when you have to link to the same site repeatedly or if using a lot of inline links is making your text difficult to read.

Inline Linking Input:

Check out [my site](http://www.mysite.com/ "My Website")

Output:

Check out my site

Notice how the words to be linked are within square brackets with the actual web address in round brackets immediately after. The third item contained in quotes is an optional title for the link. Whatever you put in quotes will appear as a tooltip when you place the mouse cursor over the link without clicking on it. If you don't want to use a title then just close the round brackets immediately after the address.

Reference Linking Input:

Check out [my site][id]
Then further down in the document define the reference ID.
[id]: http://www.mysite.com/ "My Website"

Output:

Check out my site

You can see why this is more useful when referencing the same site repeatedly, since you only have to define the site's details once and use the reference's ID tag each time you need to reference it. If you have many hyperlinks, it also makes the post easier to write since you can put all the details at the bottom and not clutter what you're writing with link information.

Also, any website (of the form (http://www.example.com/) entered as text will automatically be converted to a clickable link without the need for tags. If you also want to include a clickable link to an email address just enter the address with angled brackets surrounding it, () and Markdown will convert that to a clickable "mailto" link.

Block Elements

These elements are used to either organize your text on screen or differentiate one section of text from another (like when you post a quote from another user for example).

Paragraphs and Line Breaks

Markdown treats consecutive lines of text the same way a word processing program would. That is to say each paragraph is one or more lines of text separated by a blank line. (A blank line is defined as a line that "looks" blank, a line with only spaces or tabs would be considered blank.)

To force a line break without having to leave a blank line, all you need to do is end the line with 2 or more spaces and hit enter.

Input:

One fish, two fish(no spaces)
Red fish, blue fish

Output:

One fish, two fish Red fish, blue fish

Input:

One fish, two fish(space)(space)
Red fish, blue fish

Output:

One fish, two fish
Red fish, blue fish

Headers

Headers are defined using the hash mark symbol (#). If a newline starts with 1-6 hash marks then a space, any text on that line will be formatted to match the six predefined HTML heading styles.

Input:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Output:

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

Notice that I didn't need to use the double space technique described above to put each header on its own line. If the last line is a header then the next line is always considered a newline and you don't need to add any spaces before the carriage return.

Lists

Arguably the most useful Markdown tags are the ones which automatically format lines into bulleted or numerical lists. To include a line (or paragraph) as a list item start the line/paragraph with an asterisk (*) then a space. Also, be sure that the line preceding the first list item is blank.

(Plus signs(+) and hyphens(-) can also be used interchangeably with the asterisk, as long as you use the same symbol within the same list.) One other important note is that if two list items are separated by a blank line then they will be treated as two separate lists.

Input:

(Blank line)
* item 1
* item 2
* item 3

Output:

Input:

(Blank line)
* Lists can also,
(4 spaces)* contain sublists
(8 spaces)* created by indenting the tag by at least 4 spaces per level

Output:

For a numbered list, use a tag of the form (number)(period)(space). These lists can also be nested and it's also possible to create mixed lists of numerical and bulleted points. Note: the number used in the tag does not have to be the correct item number. Markdown always orders the list top to bottom starting at 1.

Input:

(Blank line)
1. Item 1,
2. Item 2,
3. Item 3

Output:

  1. Item 1,
  2. Item 2,
  3. Item 3

Block Quotes

These tags are used the add a "block" around text to differentiate it from the main body, commonly used for quoted text. When using block quotes the best practice is to start each line you wish to block with an angle bracket (>) and a space.

Input:

> This is a one paragraph block quote.

Output:

This is a one paragraph block quote.

Input:

> This is a two paragraph block quote.
>
> This is a two paragraph block quote.

Output:

This is a two paragraph block quote.

This is a two paragraph block quote.

Input:

> Block quotes can also be nested
> > by adding a second >(space) tag

Output:

Block quotes can also be nested

by adding a second >(space) tag.

Input:

> ##### Any other Markdown element...
> * can also be put in block quotes.

Output:

Any other Markdown element...
  • can also be put in block quotes.

Horizontal Rules

These are horizontal lines across the page used to separate blocks of text without changing how that text looks. To create a rule, place 3 or more asterisks on the same line. Underscores or hyphens can also be used instead of asterisks.

Input:

***

Output:


Conclusion

You now should have a basic familiarity with how Markdown works. It's a straightforward syntax but the best way to really understand it is to practice. This site allows users to enter in text using the Markup syntax then see how it would appear once its been posted. (Though do keep in mind, that site uses a slightly different Markup implementation than RTH.)

After a little bit of practice, this style of posting becomes second nature.

Most importantly, always remember the purpose of Markdown is to increase readability. If you write your whole post in the Header 1 format, don't be surprised if it starts getting downvoted. If you come across a problem or have a question, feel free to post it below.

Ryan Danks is a Project Engineer for a wind engineering consulting company. After living in Stoney Creek for many years he and his fiancée are now enjoying all Ward 2 has to offer.

4 Comments

View Comments: Nested | Flat

Read Comments

[ - ]

By seancb (registered) - website | Posted September 29, 2010 at 12:35:14

in fact it might even be cleaner without examples for the last two:

Formatting Comments with Markdown
Bold: **bold text** => bold text
Italics: *italics text* => italics text
Links: [Google](http://google.com "This goes to google") => Google
Images: ![RTH](http://raisethehammer.org/static/images/logo-banner.png) => RTH
Block Quotes: start a line or paragraph with a single > followed by a single space. Nesting is supported also: > > > Quoted Text
Horizontal Rule: place 3 or more asterisks alone on a single line

Edit: removed a link to an image on a page flagged as malware.

Comment edited by administrator seancb on 2013-06-05 14:27:49

Permalink | Context

[ - ]

By Ryan (registered) - website | Posted September 29, 2010 at 12:36:26

That's a great idea. I'll put something together.

Permalink | Context

[ - ]

By Missy2013 (registered) - website | Posted September 11, 2015 at 09:41:01

... Just wondering, how do we insert photos in comments? Is that possible?

Permalink | Context

By mdrejhon (registered) - website | Posted November 06, 2015 at 01:10:11 in reply to Comment 113839

Yes. First upload the image to www.imgur.com then copy and paste the "Markdown Link" text, then add an exclamation mark to the beginning (right before the first bracket).

Permalink | Context

View Comments: Nested | Flat

Post a Comment

You must be logged in to comment.

Events Calendar

Recent Articles

Article Archives

Blog Archives

Site Tools

Feeds