PHP Markdown: Concepts

This document introduce the concepts you need to know when you write using the Markdown syntax.

A good way to learn Markdown once you know the basics is by training yourself using the dingus (see menu above).

Paragraphs

A paragraph is defined as one or more lines of text, separated by at least one empty line:

This is a small paragraph illustrating how 
Markdown works. This paragraph span on many 
lines.

This is a second paragraph.

Here is the result:

Line breaks inserted in the text are removed from the final result: the web browser is in charge of breaking the lines depending of the available space. If you really want to force a line break somewhere, insert two spaces at the end of the line.

Emphasis

You can put emphasis some part of your text inside a paragraph. There is two types of emphasis: normal emphasis and strong emphasis. On most websites, emphasis is shown as italic while strong emphasis is bold.

To give emphasis to some text with Markdown, we use asterisks (*) or underscores (_). Surrounding some text with one asterisk or one underscore bar gives normal emphasis, while surrounding some text with two asterisks or two underscores results in strong emphasis:

*normal emphasis with asterisks*

_normal emphasis with underscore_

**strong emphasis with asterisks**

__strong emphasis with underscore__

This is some text *emphased* with asterisks.

And it gives this result:

Please note that there is absolutely no difference between using underscore and asterisks: both give exactly the same result. Choose the one you are the most comfortable with.

Links

If you want to insert an hypertext link inside your document, Markdown gives you two ways. You can write your links inline links or by reference.

Inline-style links allow linking some text to another web page. Surround the link with [brackets], followed by the URL inside parenthesis. Like this

[Michel Fortin](https://michelf.ca/)

[Michel Fortin](https://michelf.ca/ "My website")

The second link has a title (quoted) which is displayed by most web browser as a tooltip when your mouse stops over the link. The title is optional.

Refence-style links work the same, except that you do not have to write the URL in the middle of the paragraph, which makes text more legible. Instead you give a name to the link and you write the URL on a separate line — anywhere in the document. It looks like this:

This is a small text written by [Michel Fortin][mf].

 [mf]: https://michelf.ca/ "My website"

The line that define the URL is stripped from the final result and the bracketed text becomes a link:

Again, the title of the link (My website) is optional.

Automatic links

If you simply want to be able to click at an URL inserted in your text, put the URL between angle brackets and Markdown will make a clickable link with it:

<https://michelf.ca/>

<michel.fortin@michelf.ca>

Headers

You can add headers and sub-headers to your document with Markdown. Two syntaxes allow you to insert headers with up to six different levels. You can write headers of level 1 and 2 using the “SeText” syntax:

Header 1
========

Header 2
--------

The “atx” syntax can create headers of any level by changing the number of hash (#):

# Header 1 #

## Header 2 ##

###### Header at level 6

Note that the tailing hashes are optional.

Blockquote

Maybe you already seen this way of quoting someone in an email discussion:

A quote about linear algebra:

> Consistent linear systems in real life are solved in 
> one of two ways: by direct calculation (using a matrix 
> factorization, for example) or by an iterative procedure 
> that generates a sequence of vectors that approach the 
> exact solution.

You can put more than one paragraph inside a blockquote. You can also put a second blockquote level, lists, etc.

Lists

Markdown assists you when creating numbered lists (ordered) and bullet lists (unordored). To create and ordered list, use a number followed by a dot as the item marker:

1.  Snowy
2.  Elf
3.  Boreal

To create an unordered list, use *, +, or - as item marker:

*   Sun
*   Moon
*   Earth

You can nest lists by indenting by four spaces (or one tab) the lists on the second level:

*   Ingredients
    -   Milk
    -   Eggs
*   Recipies
    1.  Pancake
    2.  Waffle

If your list contains entire paragraphs, leave an empty line between list items. To write more than one paragraph under the same item, make sure that they are indented by 4 spaces (or one tab):

1.  First paragraph.

    Second paragraph.

2.  Another list item.

3.  Yet another.

Code

Code Blocks

We write a code block by indenting some lines by four spaces (or one tab):

How to mark emphasis:

    Using <em>HTML</em> and using *Markdown*.

Inside a code block, you can write HTML tags or Markdown formatting; in both cases the syntax won’t be parsed and text will be shown as is:

Using <em>HTML</em> and using *Markdown*.

Code Spans

You can make a code span in the middle of your paragraph by using the backtick (`), this way:

Please don't use the `<blink>` tag.

Which will produce the following result:

HTML

You don’t have to know HTML in order to use Markdown. But if you know some HTML tags, you can use them where you want. For example, to format some text as superscript — something not covered by the Markdown syntax — you can use the <sup> HTML tag:

Be cautious about what you read on April 1<sup>st</sup>!

Markdown will skip the tag without changing it and the browser will display text inside as superscript:

Some tags like <p> and <div> delimits text blocks. If you use these tags, special rules apply. See the Inline HTML section from the syntax desciption to learn about them.