Markdown Formatting Guide
Guides for using Markdown.
Table of Contents
Paragraph
Separate each line of text with two or more new line character to create a paragraph element on each piece:
Paragraph one.
Paragraph two.Result:
<p>Paragraph one.</p>
<p>Paragraph two.</p>Line Break
Add two or more spaces at the end of the line you want to break:
Line one. ← here!
Line two.Result:
Line one.<br>
Line two.Italic
Text wrapped with one * or _ will be replaced by <em> tag:
*italic*
_italic_Result:
<em>italic</em>
<em>italic</em>Bold
Double *’s or _’s will be replaced by <strong> tag:
**bold**
__bold__Result:
<strong>bold</strong>
<strong>bold</strong>Bold-Italic
***bold-italic***
___bold-italic___
**_bold-italic_**
__*bold-italic*__
*__italic-bold__*
_**italic-bold**_Header
Headers can be created by underlining the text with equal or dash sign (for first-level and second-level headers only):
Header 1
========
Header 2
--------Any number of underlining =’s or -’s will work:
<h1>Header 1</h1>
<h2>Header 2</h2>Another syntax by using some leading # with the same amount as the header level:
# Header 1
## Header 2
### Header 3
#### Header 4
##### Header 5
###### Header 6This also work:
# Header 1 #
## Header 2 ##
### Header 3 ###
#### Header 4 ####
##### Header 5 #####
###### Header 6 ######Block Quote
Begin each line of paragraph with the > symbol to wrap them in a <blockquote> element:
> This is a paragraph in a block quote.
>
> This is also a paragraph in a block quote.Result:
<blockquote>
<p>This is a paragraph in a block quote.</p>
<p>This is also a paragraph in a block quote.</p>
</blockquote>Nested block quotes example:
> This is the first level of quoting.
>
> > This is nested block quote.
>
> Back to the first level.List
Unordered List
Use *, - or + at the beginning of text to create unordered list items:
* List item 1
* List item 2
* List item 3- List item 1
- List item 2
- List item 3+ List item 1
+ List item 2
+ List item 3Result:
<ul>
<li>List item 1</li>
<li>List item 2</li>
<li>List item 3</li>
</ul>Ordered List
Use numbers followed by periods at the beginning of text to create ordered list items:
1. List item 1
2. List item 2
3. List item 3Note: The actual numbers you use to mark the list have no effect on the HTML output Markdown produces. So, this will also work:
9. List item 1 1. List item 2 7. List item 3
Result:
<ol>
<li>List item 1</li>
<li>List item 2</li>
<li>List item 3</li>
</ol>Nested List Items
1. Lists item 1
- List item 1.1
- List item 1.2
1. List item 1.2.1
- List item 1.3
2. List item 2Result:
<ol>
<li>Lists item 1
<ul>
<li>List item 1.1</li>
<li>List item 1.2
<ol>
<li>List item 1.2.1</li>
</ol>
</li>
<li>List item 1.3</li>
</ul>
</li>
<li>List item 2</li>
</ol>Paragraphs in List Items
If list items are separated by blank lines, Markdown will wrap the items in <p> tags in the HTML output:
* List item 1
* List item 2
Another paragraph in list item two.Result:
<ul>
<li>
<p>List item 1</p>
</li>
<li>
<p>List item 2</p>
<p>Another paragraph in list item two.</p>
</li>
</ul>Code
Inline Code
To create a code span, wrap the text you want with a backtick:
This is a paragraph with some `inline code` in it.Result:
<p>This is a paragraph with some <code>inline code</code> in it.</p>To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:
``There is a literal backtick (`) here.``Block Code
Indent some paragraph with 4 spaces or a tab to wrap them in a <pre> and <code> tag, and also automatically escape the HTML code in it:
This is a normal paragraph.
This is a code block with some <abbr>HTML</abbr> markup.
This is another normal paragraph.A code block continues until it reaches a line that is not indented (or the end of the article):
<p>This is a normal paragraph.</p>
<pre><code>This is a code block with some <abbr>HTML</abbr> markup.</code></pre>
<p>This is another normal paragraph.</p>Markdown Extra’s Fenced Code Block Syntax
The code block starts with a line containing three or more tilde or backtick characters, and ends with the first line with the same number of tilde or backtick characters:
~~~~~~~~~~~~~~~~~~~~~
This is a code block.
~~~~~~~~~~~~~~~~~~~~~`````````````````````
This is a code block.
`````````````````````You can also specify a class name that will be applied to a code block like this:
~~~~~~~~~~~~~~~~~~~~~~~~~ .html
<p>Example HTML code.</p>
~~~~~~~~~~~~~~~~~~~~~~~~~In the HTML output, code block attributes will be applied on the <code> element:
<pre><code class="html"><p>Example HTML code.</p></code></pre>Horizontal Rule
Create horizontal rule by placing three or more hyphens, asterisks, or underscores on a line by themselves. You may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:
* * *
***
*****
- - -
---------------------------------------Link
Markdown supports two style of links: inline and reference.
Inline Link
To create an inline link, use a set of regular parentheses immediately after the link text’s closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an optional title for the link, surrounded in quotes:
This is [an example](http://example.com "Title") inline link.
[This link](http://example.net) has no title attribute.Result:
<p>This is <a href="http://example.com" title="Title">
an example</a> inline link.</p>
<p><a href="http://example.net">This link</a> has no
title attribute.</p>Referenced Link
Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:
This is [an example][id] reference-style link.Then, anywhere in the document, you define your link label like this, on a line by itself:
[id]: http://example.com "Optional Title"The following three link definitions are equivalent:
[foo]: http://example.com "Optional Title Here"
[foo]: http://example.com 'Optional Title Here'
[foo]: http://example.com (Optional Title Here)The link URL may, optionally, be surrounded by angle brackets:
[id]: <http://example.com> "Optional Title Here"Link definitions can be placed anywhere in your Markdown document. But if you want, you can put them all at the end of your document, sort of like footnotes.
Implicit Link Name Shortcut
The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets:
[Google][]And then define the link:
[Google]: https://www.google.comAutomatic Link
If you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this:
<http://example.com>
<address@example.com>Markdown will turn the text into this:
<a href="http://example.com">http://example.com</a>
<a href="mailto:address@example.com">address@example.com</a>Image
Markdown uses an image syntax that is intended to resemble the syntax for links, allowing for two styles: inline and reference.
Inline Image
Result:
<p><img alt="alt text" src="path/to/image.jpg"></p>
<p><img alt="alt text" src="path/to/image.jpg" title="Optional Title"></p>Referenced Image
Reference-style image syntax looks like this:
![alt text][id]Where id is the name of a defined image reference. Image references are defined using syntax identical to link references:
[id]: path/to/image.jpg "Optional Title"Table
The first line contains column headers. Second line contains a mandatory separator line between the headers and the content. Each following line is a row in the table. Columns are always separated by the pipe (|) character:
Table Header 1 | Table Header 2
-------------- | --------------
Table Cell 1.1 | Table Cell 1.2
Table Cell 2.1 | Table Cell 2.2
Table Cell 3.1 | Table Cell 3.2or …
| Table Header 1 | Table Header 2 |
| -------------- | -------------- |
| Table Cell 1.1 | Table Cell 1.2 |
| Table Cell 2.1 | Table Cell 2.2 |
| Table Cell 3.1 | Table Cell 3.2 |Result:
<table class="table">
<thead>
<tr>
<th>Table Header 1</th>
<th>Table Header 2</th>
</tr>
</thead>
<tbody>
<tr>
<td>Table Cell 1.1</td>
<td>Table Cell 1.2</td>
</tr>
<tr>
<td>Table Cell 2.1</td>
<td>Table Cell 2.2</td>
</tr>
<tr>
<td>Table Cell 3.1</td>
<td>Table Cell 3.2</td>
</tr>
</tbody>
</table>Table Alignments
Add some colons to the separator lines. A colon that added at the left of the separator line will make the column left-aligned. A colon that added at the right of the separator line will make the column right-aligned. Colons that added at both side means the column is center-aligned:
Table Header 1 | Table Header 2 | Table Header 3
-------------: | :------------: | :-------------
Table Cell 1.1 | Table Cell 1.2 | Table Cell 1.3
Table Cell 2.1 | Table Cell 2.2 | Table Cell 2.3
Table Cell 3.1 | Table Cell 3.2 | Table Cell 3.3Result:
<table class="border">
<thead>
<tr>
<th class="text-right">Table Header 1</th>
<th class="text-center">Table Header 2</th>
<th class="text-left">Table Header 3</th>
</tr>
</thead>
<tbody>
<tr>
<td class="text-right">Table Cell 1.1</td>
<td class="text-center">Table Cell 1.2</td>
<td class="text-left">Table Cell 1.3</td>
</tr>
<tr>
<td class="text-right">Table Cell 2.1</td>
<td class="text-center">Table Cell 2.2</td>
<td class="text-left">Table Cell 2.3</td>
</tr>
<tr>
<td class="text-right">Table Cell 3.1</td>
<td class="text-center">Table Cell 3.2</td>
<td class="text-left">Table Cell 3.3</td>
</tr>
</tbody>
</table>Definition List
Definition list in Markdown Extra is made of a single-line term followed by a colon and the definition for that term:
Title 1
: Definition of Title 1 goes here.
Title 2
: Definition of Title 2 goes here.Colons as definition markers may be indented by up to three spaces and must be followed at least by one space or tab:
<dl>
<dt>Title 1</dt>
<dd>Definition of Title 1 goes here.</dd>
<dt>Title 2</dt>
<dd>Definition of Title 2 goes here.</dd>
</dl>Definition lists can have more than one definition associated with one term:
Title 1
: Definition of Title 1 goes here.
: Another definition of Title 1 goes here.
Title 2
: Definition of Title 2 goes here.You can also associate more than one term to a definition:
Term 1
Term 2
: Definition A
Term 3
: Definition BIf a definition is preceded by a blank line, Markdown Extra will wrap the definition in <p> tags in the HTML output:
Title 1
: Definition of Title 1 goes here.
Another paragraph of Title 1’s definition goes here.
Title 2
: Definition of Title 2 goes here.Footnote
A footnote is made of two things: 1). A marker in the text that will become a superscript number 2). A footnote definition that will be placed in a list of footnotes at the end of the document:
This is some text with a footnote. [^1]
[^1]: And this is the footnote.Footnote definitions can be found anywhere in the document, but footnotes will always be listed in the order they are linked to in the text. You cannot make two links to the same footnotes:
<p>This is some text with a footnote. <sup id="fnref:1"><a href="#fn:1" class="note-to">1</a></sup></p>
<div class="notes">
<hr>
<ol>
<li id="fn:1">
<p>And this is the footnote. <a href="#fnref:1" class="note-of">↩</a></p>
</li>
</ol>
</div>Abbreviation
Abbreviations can be created by writing some definitions at the bottom of the document like this:
*[HTML]: Hyper Text Markup Language
*[CSS]: Cascading Style SheetThis will automatically change all text that matches with the text that is in the bracket to be like this:
Some text with <abbr title="Hyper Text Markup Language">HTML</abbr> and <abbr title="Cascading Style Sheet">CSS</abbr>.Abbreviations are case-sensitive, and will span on multiple words when defined as such. An abbreviation may also have an empty definition:
*[PHP]:Special Attributes
You can set the ID and class attribute on certain elements using an attribute block:
Header 1 {#header-1}
========
## Header 2 {#header-2}The code above will produce:
<h1 id="header-1">Header 1</h1>
<h2 id="header-2">Header 2</h2>To add a class name, use a dot:
Header 1 {.header-1}
========
## Header 2 {.header-2.main}The code above will produce:
<h1 class="header-1">Header 1</h1>
<h2 class="header-2 main">Header 2</h2>Mixing ID and some class attributes in one element:
## Header 2 {.main.media-head#the-site}Special attribute blocks can be used with:
Escaping
Add a backslash at the begining of character to escape them from Markdown parser:
1986. This will become a list item.
1986\. This will not.Not a Replacement for HTML
Markdown is not intended as a replacement for HTML. If you want to use HTML code because the Markdown syntax was not possible to create it (for example, you want to add width and height attribute to an image) then you can just put it as the HTML itself.
By default, Markdown will not process the syntax within a block element, so the bold syntax in this example will not be turned into <strong> element:
<div>This is not a **bold** text.</div>You can disable this behavior by adding a markdown attribute on the block element wrapper with the value greater than zero:
<div markdown="1">This is a **bold** text.</div>Extras
Mecha uses this plugin to enable some features that are not available in the original Parsedown Extra extension. These extra features include:
- Pre-defined abbreviations.
- Pre-defined links and images.
- Ability to detect external link URLs.
- Advance attributes parser. This feature allows you to write literal HTML attributes in the attribute block like:
{#foo.bar.baz width="300" height="250"}
0 Comments
No comments yet.