Enhancing Text With Markdown

Markdown expands upon the simple text entry format available in Moodle by allowing you to easily add emphasis (bold, italics), structure (bullet points and headings) and links (to images or other web resources). You can use Markdown in many places in Moodle, simply select it from the formatting drop down list which is found below the text entry area wherever you have the choice.

To enter text simply type into the text entry area or text box, pressing the return key twice at the end of a paragraph to leave a blank line between the end of one paragraph and the start of the next.

Markdown allows you to subdivide your text with headings; six different levels are available though it is unusual for a normal text to use more than three. For example, there are three levels of heading used in the text you are currently reading.

You can create a heading by starting a line with one or more hash characters (#). One hash is the largest and most important heading, and six hashes gives you the least important or smallest heading.

The first two levels of headings are most common and can be created in alternative ways that make them stand out more in the text version (though the output is identical to the previous method). This alternative uses a line of equal signs (=) or hyphens (-) under the title as follows:

You can indicate a quoted section of text by beginning each line with an angle bracket (>). This character was chosen as many email programs use it to indicate quoted sections. The output will generally indent the quoted section in from both margins.

> This is a quoted paragraph> spread over two lines

becomes

This is a quoted paragraph
spread over two lines

You can save some typing by only using a a single angle bracket at the beginning of the first line of the paragraph

> this is all one single quotedparagraph even though it is spreadover several lines.

becomes

this is all one single quoted
paragraph even though it is spread over
several lines.

There are two ways to create links to web resources: the first is to include the link inline, placing the text you wish readers to click on in square brackets, and the URL of the page they will be taken to immediately afterwards in parentheses with no space or gap between the two sets of brackets; you can also add an optional title for the link in quotes after the URL.

An [example link](http://example.com/ "Optional Title") in a sentence.

The title, if supplied, is displayed in a 'tooltip' which appears when the user hovers their mouse over the link text. Try it on the link that appears above.

For longer links you can avoid disrupting the flow of text by using a footnote style, attaching a short identifying name to the link in a second set of square brackets (either using a short explanatory word, phrase or simply a number).

An [example link][ex] in a sentence.

Then, anywhere else in the document, but preferably either directly after the paragraph with the link, or collected with other link URLs at the bottom of the document, you can define the URL associated with the id:

[ex]: http://example.com/ "Optional Title"

The output of this second example would be indistinguishable from the first. It is simply a matter of keeping the working document neatly organised to aid further editing (particularly if you are working with others).

A final shortcut, if you wish your linked text to be the same as the URL, is to place the URL within angled brackets like so:

Images are included in a very similar manner to web links, but are preceded by an exclamation mark. The 'alt text' (alt meaning alternative) is provided to users that cannot see the image for various reasons, thus the text should make sense without any visual cues. Doing this will also provide a reminder or hint to those editing the text in Markdown as to the purpose of the image.

The 'title' is displayed in a small pop up when the user hovers over the image and so can provide additional information.

![alt text](/path/img.jpg "Optional Title")

And, like web links, you can organise your document by keeping all the URLs together with 'footnote' style references. Just give the image a short, unique name:

![alt text][photo]

and anywhere else in your document, associate that name with an image file:

This short introduction covers the features of Markdown that are used in the vast majority of cases. It is possible to achieve far more complex results, particularly if you already know how to write HTML, but these are covered in a separate document on the Advanced Use of Markdown