...Processing...
error
big error
Using Markdown at TutnIQ - TutnIQ
Table of contents X
  • Getting technical with Markdown and TutnIQ: Code and mathematics

    In this section we will learn how to use TutnIQ to embed code snippets and mathematical equations in Markdown text. We will also learn the intricacies of escaping special characters.

  • 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:

    • List item 1
    • List item 2

    <?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).
  • Online resources:
« Previous
[Section: 3 of 3]
ad placeholder

Sharing is caring!

About the author

Course stats

My progress

Find related courses