...Processing...
error
big error
Using Markdown at TutnIQ - TutnIQ
Table of contents X

Using Markdown at TutnIQ

Markdown is a human readable text formatting syntax

  • Markdown is a plain text syntax which is easy to read and write, and is used by a variety of popular websites. You can use Markdown to format text at TutnIQ in specified text input form areas.

  • Introduction

    Markdown allows us to format plain text with headers, bold and italicized text, lists, fancy quotes and clickable links, but maintains the advantages of plain text.

    Markdown was invented by John Gruber in 2004,

    The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

    TutnIQ supports standard Markdown with a few limitations and enhancements.

  • Getting started with Markdown: Headings, paragraphs and emphasizing text

    In this section we will learn how to create headings, lay out paragraphs and emphasize text.

  • Headings

    We can indicate a heading in Markdown by using the hash ( # ) symbol. One hash indicates a very important heading, and 5 hashes a heading that is less important. Each of these is displayed slightly differently. This:

    # This is a heading 1 (H1)
    ## This is a heading 2 (H2)
    ### This is a heading 3 (H3)
    #### This is a heading 4 (H4)
    ##### This is a heading 5 (H5)   
    

    Will produce the following output:

    This is a heading 1 (H1)

    This is a heading 2 (H2)

    This is a heading 3 (H3)

    This is a heading 4 (H4)

    This is a heading 5 (H5)

    We can use closing hashes, but these are optional. Example: ###Closing hashes follow###.

    Alternatively, for H1 and H2, we can indicate a heading by underlining with the equal (=) or dash (-)symbol respectively. This:

    Alternative syntax: H1
    ======================
    
    Alternative syntax: H2
    ----------------------
    

    Will produce the following output:

    Alternative syntax: H1

    Alternative syntax: H2

    Information boxes

    TutnIQ treats a 6-hash heading as an information box. An information box is useful for emphasizing a block of information. This functionality is specific to TutnIQ, on other sites a 6-hash heading will simply appear as a heading. This:

    ######  This treatment is unique to TutnIQ.
    

    Will produce the following output:

    This treatment is unique to TutnIQ.

    Paragraphs and line breaks

    A blank line starts a new paragraph.

    Two spaces at the
    end of a line[space][space]
    indicate a line break.
    This is useful for poetry,
    or postal addresses.

    Emphasis of text

    We can call attention to text in Markdown by emphasizing the text with italics, bold or both using asterisks and underscores. This:

    Emphasis, aka italics, with *asterisks* or _underscores_.  
    Strong emphasis, aka bold, with **double asterisks** or __double underscores__.  
    Combined emphasis with **asterisks and _underscores_**.  
    

    Will produce the following output:

    Emphasis, aka italics, with asterisks or underscores.
    Strong emphasis, aka bold, with double asterisks or double underscores.
    Combined emphasis with asterisks and underscores.

    Horizontal lines

    We can rule a line across the page with: --- or ___ or === on a separate line (with a blank line above):


  • Getting fancy with Markdown: Quotes, links and lists

    In this section we will learn how to create fancy quotes, bullet point lists, numbered lists and clickable links with Markdown and TutnIQ.

  • Blockquotes

    Blockquotes are indicated by > angle brackets in Markdown. This:

    > Blockquotes can be used to indicate quoted text.
    > This line is part of the same quote.
    

    Will produce the following output:

    Blockquotes can be used to indicate quoted text. This line is part of the same quote.

    A few other features of a blockquote:

    > A blockquote can *contain* **Markdown**. 
    > Very long lines will be quoted properly when they wrap. This sentence is intentionally very long and repetitive to demonstrate that it will wrap properly.  This sentence is intentionally very long and repetitive to demonstrate that it will wrap properly.  This sentence is intentionally very long and repetitive to demonstrate that it will wrap properly.  This sentence is intentionally very long and repetitive to demonstrate that it will wrap properly. 
    

    Will produce the following output:

    A blockquote can contain Markdown. Very long lines will be quoted properly when they wrap. This sentence is intentionally very long and repetitive to demonstrate that it will wrap properly. This sentence is intentionally very long and repetitive to demonstrate that it will wrap properly. This sentence is intentionally very long and repetitive to demonstrate that it will wrap properly. This sentence is intentionally very long and repetitive to demonstrate that it will wrap properly.

    Nested blockquotes:

    > Nested blockquotes allow one quote to be quoted in another
    >
    >> This is the nested quote.
    

    Will produce the following output:

    Nested blockquotes allow one quote to be quoted in another

    This is the nested quote.

    Lists

    Bullet point lists

    Markdown can be used to create bullet point (unordered) lists, by using asterisks, pluses, and or hyphens (*, +, or -) as list markers. These list markers are interchangeable. There must be at least one space between the list marker and the first letter of the list item. This:

    -  Apples
    +  Pears
    *  Oranges
    

    Will produce this output:

    • Apples
    • Pears
    • Oranges

    Numbered lists

    Markdown can also be used create numbered (ordered) lists. We use numbers, followed by periods, as list markers. There must be at least one space between the period and the first letter of the list item. This:

    1. Red
    2. Orange
    3. Yellow   
    

    Will produce this output:

    1. Red
    2. Orange
    3. Yellow

    We do not have to correctly number the list items as Markdown takes care of the numbering automatically. This:

    9999. First item
    23. Second item
    8. Third item
    

    Will produce this output:

    1. First item
    2. Second item
    3. Third item

    Paragraphed list items

    We can create paragraphed list items by inserting a blank line between each list item. This

    - Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. 
    
    - Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text.
    
    - Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text.
    

    Will produce this output:

    • Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text. Paragraph 1 text.

    • Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text. Paragraph 2 text.

    • Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text. Paragraph 3 text.

    Multi-paragraph list items containing Markdown

    We can create multi-paragraph list items by indenting the subsequent paragraphs by 4 spaces. A list item can also include other Markdown formatting. This:

    - This is paragraph 1 of list item 1.
    
        Second paragraph (indented by 4 spaces).
        >and a blockquote (indented by 4 spaces).       
    
    - List item 2 contains a nested list
     - Nested item 1
     - Nested item 2
    

    Will produce this output:

    • This is paragraph 1 of list item 1.

      Second paragraph (indented by 4 spaces).

      and a blockquote (also indented by 4 spaces).

    • List item 2 contains a nested list

      • Nested item 1
      • Nested item 2

    Links

    Markdown can be used to create clickable links in a number of ways.

    Automatic links

    Links will be automatically clickable if enclosed in angle brackets, < and >. This also applies to email addresses. This:

    Email me at <email_address_goes_here> and I will never get your emails.   
    This is a website: <http://www.example.com>.  
    

    Will produce this output:

    Email me at [email protected] and I will never get your emails.
    This is a website http://www.example.com.

    In-line links

    We use square brackets to indicate the text we want to turn into a link, and enclose the URL with round brackets. We can also include an optional title which will appear when a user hovers on the link. This:

    This is an [example](http://example.com/ "Optional title in double quotes - separated from the link with at least one space") of an inline link.
    

    Will produce this output:

    This is an example of an inline link.

    Reference links

    Reference links allow us to reference our links with names which have been defined elsewhere in the text. This is useful if we need to link to the same URL many times. Link names may contain alphanumeric characters and spaces, and are not case sensitive. We use square brackets to indicate the text we want to turn into a link, and square brackets to reference the link name.

    This (the reference link names are 1,2):

    TutnIQ supports embedding of video from [YouTube][1] and [Vimeo][2].
    
    [1]: http://www.youtube.com/  "YouTube - this title appears when we hover on the link and is optional"
    [2]: http://www.vimeo.com/  "Vimeo"
    

    Will produce this output:

    TutnIQ supports embedding of video from YouTube and Vimeo.

    A web address should always start with http:// or https://. If you omit this, Markdown will assume that link is an internal TutnIQ link - if this is not your intention, the link will be broken.

    Images

    TutnIQ does not currently support image uploads, or images in Markdown formatted text.

    Instead of manually including images in Markdown we suggest that you use the "Embed web content" option under the "Add content" menu in the course builder to embed images in your course (restricted to sites supported for embed purposes, for example: Flickr).

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

Sharing is caring!

About the author

Course stats

My progress

Find related courses