How to use markdown in comments

Markdown is intended as a way of formatting text in an easy-to-read and easy-to-write way. Some of our courses have markdown enabled. The comment box will look like this:

[Image descriptor: The above image shows a large comment box with the text 'Add a comment... (plain text and markdown available)' inside. Under the box is a character count showing 0/1200. Above the comment box is a orange flag showing the initials of the Example Learner (EL) and next to that is the name of the Example Learner in full] 

If the Markdown doesn't look the way you expect, you can click the Edit button to the bottom-right of your comment and have another go.

Contents

• Bold and Italics
• Paragraphs and line breaks
• Links
• Lists
• Blockquotes
• Tables
• Headers
• Code
• Advanced

Bold and Italics

Text wrapped with one *asterisk* or _underscore_ will be italicised ;

Text wrapped with two **asterisks** or __underscores__ will be displayed as bold text.

If you surround an * or _ with spaces, it’ll be treated as a literal asterisk or underscore.

Paragraphs and line breaks

To separate text into paragraphs, press return twice.

This creates a new paragraph just like you would in a word processor.

When you want to insert a line break, end the sentence with two spaces and press return. This creates a line break without creating a new paragraph. It is the equivalent of the <br /> break tag in HTML.

Links

Where Markdown is supported, URLs are not auto-linked. You can quickly make a URL into a link like this:

<https://www.futurelearn.com>

becomes:

https://www.futurelearn.com

You can also make text into a link by putting the link text in [square brackets] immediately followed by the URL inside parentheses ( and ):

[Go to FutureLearn’s website](https://www.futurelearn.com/)

becomes:

Go to FutureLearn’s website 

Lists

Markdown supports numbered and bulleted lists.

You can use asterisks (*), pluses (+), and hyphens (-) interchangeably – as bullet points:

• You can use asterisks…
• …pluses…
• …and hyphens interchangeably as bullet points. Make sure you leave a blank line before and after the list.
• You will need to enter text after the list for it to display correctly.

Numbered lists use numbers followed by periods:

1. Ordered lists use numbers followed by periods
2. Once again, make sure your ordered list is a separate paragraph.
3. If you want to create a list item with multiple paragraphs, press return twice and indent each subsequent paragraph with four spaces (or one tab).
   
   Voila! you have a second paragraph!

Blockquotes

Blockquotes are used to display quotes and excerpts.

> Blockquotes are displayed by preceding text with a greater than symbol.

becomes:

You can put paragraphs into a block quote by putting an empty line that starts with the greater than symbol:

> Blockquotes are displayed by preceding text with a greater than symbol.
>
> This is a new paragraph

becomes:

Tables

We recommend no more than two-column tables because we want to ensure that they display well on mobile devices. The following snippet:

| Col1 Header  | Col2 Header |
| -------------| ------------|
| data1        | data3       |
| data2        | data4       |
| data3        | data5       |

will create a two-column table with four rows, including a header row:

[Image descriptor: The above image shows the markdown code above, rendered on-site as a table with two columns and four rows]

Make sure to leave a blank line before and after the table.

Headers

Use one or more hash (#) characters at the start of the line. All headers will be presented as the same size.

# This is a header

becomes:

Code

Pre-formatted code blocks are used for writing about programming or source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally.

Within a normal line

You can insert code into a line by wrapping it with backtick quotes (`).

Code blocks

There are different options for writing a block of code:

• indent every line of the block by at least 4 spaces or 1 tab. The code block will continue until it reaches a line that is not indented, or the end of your comment.
• with three ~ (tilde) characters at the start and end of the code block.

Regular Markdown syntax is not processed within code blocks. For example, *asterisks* are just literal asterisks within a code block.

Syntax highlighting

We support syntax highlighting in over 70 languages, including Ruby, Python and Erlang. To enable syntax highlighting on a code block use the following format:

~~~ language name
  # code goes here
~~~

For example:

~~~ ruby
class Dog
  def initialize(breed, name)
    @breed = breed
    @name = name
  end

  def bark
    puts 'Ruff! Ruff!'
  end
end
~~~

becomes:

Horizontal rules

You can produce a horizontal rule by placing three or more hyphens…

- - -

…asterisks…

***

…or underscores…

_ _ _

…on a line by themselves, with an empty line before and after. 

They look like this:

Advanced

Escaping Markdown syntax can be done be preceding the character with a backslash:

\*literal asterisks\*

This is supported for:

\ backslash

` backtick

* asterisk

_ underscore

{} curly brackets

[] square brackets

() parentheses

# hash mark

+ plus sign

- hyphen

. period

! exclamation mark

< less than

> greater than

HTML tags

We support directly writing a limited set of HTML tags:

a pre code em strong br hr h1 h2 h3 h4 h5 h6 p ul ol li table tbody thead tfoot tr td th sub sup blockquote cite div

The <a> tag supports the href, title and id attributes.

Any other tag or attribute will not be displayed. If you need to write HTML, we recommend putting it inside single backpacks (`) or a codeblock.

Subscript and Superscript

You can use the HTML tag directly for Superscript and subscript text:

This is text with some <sub>subscript</sub>

will produce:

[Image descriptor: The above image has text only reading 'This is text with some superscript' and the word superscript is slightly smaller and lower down in placement next to the rest of the sentence]

 

and:

This is text with some <sup>superscript</sup>

will produce:

[Image descriptor: The above image has text only reading 'This is text with some superscript' and the word superscript is slightly smaller and higher up in placement next to the rest of the sentence]

Mathematical Symbols

We support the embedding of mathematics inline and as block elements. Maths is written using fragments of the LaTex language surrounded by `$$` symbols. This is rendered in the page using the MathJax library (https://www.mathjax.org/), which has excellent documentation on its homepage. More details about how to use the TeX commands available in MathJax can be found at Carol Fisher’s “TeX Commands Available in MathJax” page (http://www.onemathematicalcat.org/MathJaxDocumentation/TeXSyntax.htm).

You can render Maths by wrapping your Maths formula within double dollar signs (`$$`).

To keep it inline:

    We can render $$x$$, $$y$$ and $$\frac{x}{y}$$

becomes:

[Image descriptor: The above image shows a comment stating 'We can render x, y, and x over y']

To display block level Maths:

    "Here is an interesting equation:

    $$

    \frac{\partial^2\psi}{\partial x^2} = \frac{1}{c^2}\frac{\partial^2\psi}{\partial t^2}

    $$

    What is it?"

becomes:

[Image descriptor: The above image shows a comment stating 'Here is an interesting equation:'. Beneath it is the same formula as above represented as a mathematic equation. Beneath that is the text 'What is it?']