## Code

Markdown can be used to present code snippets, displayed either in-line or as a block. This is useful for tutorials dealing with computer programming, or for highlighting syntax (as in this tutorial).

### In-line display

We indicate an in-line code snippet by wrapping the snippet in backtick quotes ( ```

).

This:

```
This is an in-line code snippet `print "hello cruel world";`.
```

Will produce this output:

This is an example of an inline code snippet, `print "hello cruel world";`

TutnIQ will attempt to highlight the keywords in *in-line* code snippets automatically (syntax highlighting).

### Block display

We can show a code snippet as a block by indenting every line of the snippet with 4 spaces.

```
<?php
echo "hello cruel world";
?>
```

- TutnIQ will automatically color alternating lines, but line numbers and syntax high-lighting will not be available for code blocks created in this way.
- When using the TutnIQ course builder we recommend that you use the "Add code snippet" option under the "Add content" menu to create code blocks - line numbers and syntax high-lighting will be automatically enabled. You will also be able to optionally indicate the programming language to optimize syntax highlighting.
- Fun fact: HTML tags, Markdown characters, and mathematical equations will not be parsed if included in a code snippet - they will be displayed as typed.

### Code blocks and lists

If you would like to include a code block in a list, you must indent the code block with an *additional* 4 spaces for every level of list indentation. This is necessary as the Markdown parser cannot tell the difference between a code block and a paragraph included as part of a list item (both are indented by 4 spaces...).

This is also the reason why creating a code block immediately after a list can be difficult. The Markdown parser will assume that you intended the indented text to be a paragraph and not a code block.

In order to ensure that a code block renders correctly in this situation it is necessary to 'break out' of the list. You can do this by:

- Giving your code block a heading (
`###Code block heading`

);
- Separating your code block from the list with an HTML comment (
`<!-- break out of list -->`

). This will only work if your Markdown implementation allows arbitrary HTML (TutnIQ does **NOT**).
- Using the
`[listbreak /]`

shortcode. This will only work on TutnIQ.

This demonstrates the use of the `[listbreak /]`

shortcode:

```
- List item 1
- List item 2 [listbreak /]
<?php
echo "This will be rendered correctly";
?>
```

will appear as:

```
<?php
echo "This will be rendered correctly";
?>
```

## Mathematical equations

TutnIQ's implementation of Markdown uses MathJax to display beautiful mathematical equations. We support the use of LaTeX (math-mode macros only) for formatting mathematical equations. The LaTeX mathematics delimiters recognised by TutnIQ are:

`\(...\)`

for in-line mathematics; and
`\[...\]`

for equations displayed as a block.

We do **not** recognise `$`

signs as delimiters.

### In-line display

This:

```
This expression \(\sqrt{3x-1}+(1+x)^2\) is an example of an in-line equation.
```

Will produce this output:

This expression \(\sqrt{3x-1}+(1+x)^2\) is an example of an in-line equation.

### Block display

Maxwellâ€™s equation in LaTeX format:

```
\[ \begin{aligned} \nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} & = \frac{4\pi}{c}\vec{\mathbf{j}} \\ \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\ \nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\ \nabla \cdot \vec{\mathbf{B}} & = 0 \end{aligned} \]
```

Will produce this output:

\[ \begin{aligned} \nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} & = \frac{4\pi}{c}\vec{\mathbf{j}} \\ \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\ \nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\ \nabla \cdot \vec{\mathbf{B}} & = 0 \end{aligned} \]

- We recommend that you use a mathematical equation editor capable of exporting equations to the LaTeX format.
- When using the TutnIQ course builder you can use the "Add mathematical formula" option under the "Add content" menu to embed mathematical equations.
- Fun fact: Markdown characters between LaTeX math delimiters will not be parsed as Markdown - they will be treated as LaTeX.

## Escaping special characters

For aesthetic and security reasons TutnIQ's implementation of Markdown does not allow the use of arbitrary HTML tags. HTML tags will be automatically escaped:

<p>This is a paragraph tag - the paragraph tags appear in the text because they have been escaped!</p>

It is not necessary to manually escape HTML entities (example: & < ) - this will happen automatically.

It is not necessary to escape special characters in code snippets.

### Escaping Markdown characters

Double-backticks can be used to delimit literal backticks in code snippets. This

```
``This is a literal backtick (`).``
```

Will produce this output: `This is a literal backtick (`).`

The backslash character `\`

can be used to escape the following characters which have significance in Markdown: \ ` * _ { } # + - . !. **This is only necessary if you find that TutnIQ is not treating these characters literally.**

The characters, [ ] and ( ) also have special meaning in Markdown, however if you escape these characters with a backslash `\`

, TutnIQ will assume that you are delimiting mathematical equations in LaTeX format `\[...\] \(...\)`

.

Generally, the Markdown parser is sufficiently intelligent to ignore square and round brackets if they do not make syntactical sense (for example: links).

## Limitations and extensions of TutnIQ-flavored Markdown

Features of Markdown, as originally created by John Gruber, not supported by TutnIQ:

- Use of arbitrary HTML tags.
- Escaping of square and round brackets:
`( ) [ ]`

.
- Image embedding (use the "Embed web content" option under the "Add content" menu instead).

Features of TutnIQ-flavored Markdown not found in standard Markdown:

- Support for mathematics in LaTeX format:
`\[...\] \(...\)`

.
- Information boxes (6-hash headings) (treated as a normal heading in standard Markdown).