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.
Basic Concepts
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.
Emphasising Text
You can add three levels of emphasis with Markdown, italic text, bold text, or bold and italic text. This is achieved by surrounding the text you wish to emphasise with asterisks e.g.
*italic* -> italic
**bold** -> bold
***bold italic*** -> bold italic
Emphasis can be added to single words, a sequence of words, or even parts of words:
a *single* word -> a single word
***a sequence of words*** -> a sequence of words
in**distinguish**able -> indistinguishable
Underscores (_) can be used interchangeably with asterisks for this purpose.
Headings
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.
# section heading
## sub-section heading
### sub-sub-section heading
etc.
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:
section heading
===============
subsection heading
------------------
Lists
bullet point lists
Bullet point lists can be created by starting each line with an asterisk followed by a space before the content of the bullet point. Note that the space is important and should not be forgotten.
* first point
* second point
* third point
becomes
- first point
- second point
- third point
Numbered Lists
Similarly, numbered lists can be created by starting each line with a number followed by a space and then the relevant text.
1. first point
2. second point
3. third point
becomes
- first point
- second point
- third point
Indented Lists
You can nest or indent bullet and numbered lists, even mixing bullet point and numbered lists in one structure:
* top level bullet one
* sub-bullet
* sub-bullet 2
* top level bullet two
1. numbered point one
1. nested numbered point
2. numbered point two
becomes
- top level bullet one
- sub-bullet
- sub-bullet 2
- top level bullet two
- numbered point one
- nested numbered point
- numbered point two
- numbered point one
quoted paragraphs
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 quoted
paragraph even though it is spread
over several lines.
becomes
this is all one single quoted paragraph even though it is spread over several lines.
Web Links
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.
becomes
An example link 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:
<http://moodle.org/>
which becomes
Images
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.
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:
[photo]: /url/to/img.jpg "Optional Title"
Here is an example followed by its output:
The 'alt text', which is also important for accessibility reasons, will often be used by browsers when links to images are broken or temporarily unavailable:
becomes (exact output dependant upon your browser)
Advanced Topics
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