Markdown Primer

This section covers the various markdown formatting options we can use We also cover the major differences between the markdown used here, and options that may be available elsewhere.

There is also a very nice Markdown Guide

Document Header

Is used to contain metadata for the marking, and is put at the top of the document between three dashes.

As per pandoc, metadata is stored in YAML format, which is basically a set of key : value pairs.

Each template style will have its own metadata options, which you can find in the docs for the template.

An example of meta data, could be

---
mod_title: Coursework Demo
mod_code: NCC-1701
cw: "CW1: Report"
student: A. Student
sid: Stu-001
---

Headings

Headings are denoted by a the hash # symbol. The number of hashes denotes the level of the Heading.

Heading level 1 (a single hash) is used to define different sections of the report. Some templates may have expected sections. These will be in the docs for the relevant template.

Markdown

# Heading Level 1
## Heading level 2
### Heading level 3

Rendered

Heading level 1

Heading Level 2

Heading Level 3

Warning

I currently don't parse the alternate heading format using underscores If that really bothers you, file a bug report with some decent justification.

Headings with marks

The parser can also take account of marking in the header. Marks can be tracked, and summarised at the end of the report.

To Add marks we append them in square brackets following a Level 1 heading. using either [awarded] or [awarded / availabe]

# Task 1  [10]
# Task 2  [10/50]

Note

Currently we only support marks at the top level heading. I can see the case for sub marks, but it makes the parsing more complex. When I encounter it as an issue (and when I get time) it will be added

Paragraphs

We just write normal text, use a blank line to separate paragraphs.

Markdown

This is our first sentance.
This senstance is also part of the paragraph.

Having a empty line denotes a new paragraph.
Also whitespace is formatted sensibly.    So who cares how many spaces we have after a stop

Rendered

This is our first sentence. This sentence is also part of the paragraph.

Having a empty line denotes a new paragraph. Also whitespace is formatted sensibly. So who cares how many spaces we have after a stop

Emphasis

We can also have Bold or Italic text. Surround the text to be emphasised with either asterisk * or underscore _:

For example

a single * for italic
double `** for Bold
triple *** for Bold and Itallic

Markdown

This text is *italic*

This text is **Bold**

This text is ***Bold and Itallic```

Rendered

This text is italic

This text is Bold

This text is ***Bold and Itallic```

Note

There is no underline supported. John Gruber gives some good reasons for this, I see no reason to disagree with him

Lists

Unordered lists.

Represent unordered list items using:

A dash -
A plus +
An asterisk *

Markdown

  - item 1
  - item 2
  - item 3

Rendered

item 1
item 2
item 3

We can also nest list items through indentation

Markdown

  - item 1
    - Sub Item 1
  - item 2
    - Sub item 2
  - item 3

Rendered

item 1
- Sub Item 1
item 2
- Sub Item 1
item 3

Spaces and Symbols for lists

We dont care what symbol you use or even if you are consistant.

The spacing at before the symbol isnt really needed. I do it through habit, as I think it makes the list stick out. It also seems more consistant with nested lists

(I also only use dash, I blame that on the Orgmode days)

Descriptive Lists

List items can be more than one line. Anything indented at the same level as the list item will be included as part of it.

markdown

  - This is a longer list item.
    You can see it continues below

    We can even have paragraphs or ```code```

  - Second List item

  - **Descriptive List**

    Mixing this with bold is OK for faking descriptive lists.

rendered

This is a longer list item. You can see it continues below

We can even have paragraphs or code
Second List item
Decriptive List

Mixing this with bold is OK for faking descrptive lists.

Numeric Lists

Use the same formatting concepts as other lists. This time we use a number followed by a full stop to represent list items.

markdown

  1. Ordered List
  1. Second Item
    1.  Sub Item
  1.  Third item

rendered

Ordered List
Second Item
1. Sub Item
Third item

Note

Markdown doenst care what numbers you use. (Except 1. for the first item) The List will be rendered and numbered in the order in the file.

I tend to end up doing

``` 1. First Item 2. Second Item ````

Links

For links we put the link text in brackets [] and the link itself in parenthesis ()

markdown

See [another website](http://www.example.org)

rendered

See another website

Warning

Markdown does support including images, using a Exclamation mark before the link However, support here is a bit sketchy.

If you share the the reports are pure HTML you would need some way of hosting the image so it can be found. Obviously, this may not be the best Idea with marking.

You do have a couple of options.

Host the image somewhere, and link out to it.
Use the image locally, and distribute the feedback as a PDF (using the browser print)

Tables

Tables can be represented by wrappign each Column in a pipe | If you want a header you can use dashes to split the heading line

Markdown

| Header 1 | Header 2 |
|----------|----------|
| Data 1   | Data 2   |
| Data 1a  | Data 2a  |

Rendered

Header 1	Header 2
Data 1	Data 2
Data 1a	Data 2a

Note

Other table formats are supported. But never really got on with them (and emacs has a nice auto format)

This should work, but YMMV

Header 1   Header 2
--------   --------
Data 1     Data 2

Warning

Multi Line headers in tables don't really work consistantly Avoid them in you can

Code

Inline Code

You can have inline code examples by surrounding text with three backticks ```

markdown

Consider using format strings ```"text {0}".format(data)``` here

rendered

Consider using format strings "text {0}".format(data) here

Code Blocks

We can also have multi line code blocks. For this use either backticks or tildes, and optionally the language.

The renderer does a pretty good job working out what language you are using but its not infallible.

markdown

Python

~~~python

def hello(user):
    print("Hello {0}".format(user))
~~~

Java

```java
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

```

Rendered

Python

def hello(user):
    print("Hello {0}".format(user))

Java

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

Indentation for code

Again, the markdown standard should allow us to use indentation for code blocks. However, I prefer fenced code as it makes things easier to read

Literate programming

We cant run code and show the output (yet) Its on the Wishlist.

Maths

Is supported via Mathjax

Documentation is incorrect

Is supported, but not currently in the Docs (Need to match sync plugins) Hopefully I can get both to work in the same way.

Mathjax is a bit new to me. Help configuring from a Mathjax Wizard would be awesome

Inline Maths

Euler's formula is remarkable: $ e^{i\pi} + 1 = 0 $

Block Maths

And other block maths $$y = mx+c$$

Latex style maths

Also Works

\begin{equation} \label{eq:stokes} \int_{\partial\Omega} \omega = \int_{\Omega} \mathrm{d}\omega \,. \end{equation}