Using Markdown¶

Basic Markdown Syntax¶

Header
======

1. First item
2. Second item
3. Third item

* First item
* Second item
* Third item

This text is *italic*

This text is **emphasized**

This text has a [link to wikipedia](http://wikipedia.org/).

![Image description](http://example.com/image.png)

Header | Header | Header
-------|--------|-------
Cell   | Cell   | Cell
Cell   | Cell   | Cell

Code Samples¶

When writing reviews, It’s often very useful to write small snippets of code. Markdown allows you to notate which parts of your text are code or terminal text, and optionally render code with syntax highlighting. This can be especially nice for proposing changes.

Code can be formatted inside a line by enclosing the text in single backticks. This is often useful when referring to symbols from the code:

I think it would be nice if you moved this code up near the `do_foo` method.

Longer code samples can be denoted using block notation. Any blocks which are indented at least 4 spaces will be treated as a code block. This code will not be syntax-highlighted, but instead will be shown as plain text.

The following code block will not be syntax-highlighted.

    def test():
        logging.error('Test failed')

In addition, code blocks can be notated without indentation by surrounding the block with triple backticks using the syntax from GitHub Flavored Markdown.

The following code block will not be syntax-highlighted.

```
function test() {
    console.log('Test failed');
}
```

You can specify a language name after the first set of backticks in order to enable syntax highlighting for the code. For instance:

The following code block WILL be syntax-highlighted.

```javascript
function test() {
    console.log('Test passed!');
}
```

Some of the most common language codes you may want to use include:

• C: c
• C++: cpp, c++
• C#: csharp
• CSS: css
• CoffeeScript: coffeescript
• HTML: html
• JSON: json
• Java: java
• JavaScript: javascript, js
• Objective-C: objective-c, obj-c, objc
• Objective-C++: objective-c++, obj-c++, objc++
• PHP: php
• Perl: perl, pl
• Python 3: python3, py3
• Python: python, py
• Ruby: ruby, rb
• Snobol: snobol
• XML: xml

For the complete list, look through the Pygments list of lexers. Any of the “short names” listed can be used.

Emoji¶

Review Board’s Markdown mode supports Emoji Shortcodes. These allow for referencing Emoji characters by name (such as :thumbsup:), and should be familiar to people using Slack, GitHub, and other services (in fact, we use GitHub’s Gemoji set for Review Board).

The advantage of Emoji Shortcodes is that they work on any database setup (MySQL users cannot use normal Unicode-based Emoji by default), and are safer for inclusion in commit messages.

Here are some examples of Emoji Shortcodes:

:smile:

:heart:

:thumbsup: :+1:

:thumbsdown: :-1:

:bug:

:cloud:

:bulb:

:trophy:

You can see a standard list of Emoji Shortcodes on this Emoji cheat sheet. (Note that this is maintained by a third-party, and may not always be accurate).

Escaping¶

Because Markdown syntax endows many common punctuation symbols with special meaning, these can sometimes unintentionally trigger formatting. In this case, you can avoid this by escaping the relevant character with a backslash:

I really want a \` backtick in this line.

Backslash escapes can be used for the following characters:

\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash mark
+ plus sign
- minus sign
. period
! exclamation mark

Uploading Images¶

You can upload images into any Markdown-capable text field (comments, replies, review request fields, etc.) by dragging-and-dropping from your file manager into the field. This will upload the image and then create a Markdown reference to it.

While the image is uploading, the text field should be left open in order for the Markdown reference to update.