Markdown Introduction


        
                Markdown 11.02 KB
                                    
                        | None                    
                
                                        |
    0    0                            

            
                                    raw
                    download
                    clone
                    embed
                    print
                
                                    report
                
                
            Markdown Introduction
<table>

<tr><td><b>Author</b></td>      <td>Manfred Rosenboom (<a href="mailto:[email protected]">[email protected]</a>)</td></tr>

<tr><td><b>Last Update</b></td> <td><time datetime="2018-03-20T11:24+0100">20-MAR-2018 11:24 CET</time></td></tr>

<tr><td><b>License</b></td>     <td><a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a></td></tr>

</table>

<a name="top"></a>Introduction
Let's begin with a quote of the Markdown site:

Markdown is a text-to-HTML conversion tool for web writers.

Markdown allows you to write using an easy-to-read, easy-to-write

plain text format, then convert it to structurally valid XHTML

(or HTML).

This text gives a short overview about the main Markdown features.
For a formal and more precise descritpion have a look at the

CommonMark specification
Markdown Syntax Examples
Headings
You can use 6 types of headings. All of them are marked with one or more #

characters at the begin of  a line.
# Header 1
Header 1
## Header 2
Header 2
### Header 3
Header 3
#### Header 4
Header 4
##### Header 5
Header 5
###### Header 6
Header 6

Paragraphs
This is a simple multi-line paragraph. All text is in one paragraph.

The current paragraph will end when an empty line is found.
After an empty line starts a new paragraph.

Line Breaks
This is a simple one-line text.

We add a second line of text with a soft-break

(2 spaces at the end of the first line)

Bold and Italic Text
**bold** : bold text
__bold__ : bold text
*italic* : italic text
_italic_ : italic text
Now we write bold (bold) and italic (italic) in one line.

Quotation
>To be or not to be.

To be or not to be.


Ordered List
1. first item
2. second item
3. third item
...

Sample:
1. first element of an ordered list  
   2nd line of the first element  
   (each above line ends with 2 spaces)
2. second element of an ordered list
3. guess what: third element of an ordered list

first element of an ordered list

2nd line of the first element

(each above line ends with 2 spaces)
second element of an ordered list
guess what: third element of an ordered list


Unordered List
* first item
* second item
* third item
...

Sample:
* first element of an unordered list
  * unordered sublist
    1. ordered subsublist
* second element of an unordered list

first element of an unordered list

unordered sublist

ordered subsublist


second element of an unordered list


Automatic Link
You can insert links directly in angle brackets to your text:
<https://www.google.com/>
The output in HTML will be similar to the following:
<a href="https://www.google.com/">https://www.google.com/</a>
https://www.google.com/
<[email protected]>
The output in HTML will be similar to the following:
<a href="mailto:[email protected]">[email protected]</a>
[email protected]
Link
[title](link)

Sample:
[German Wikipedia](de.wikipedia.org)
Link: German Wikipedia.

Link Reference
[title][reference]
[reference]: link

Sample:
[German Wikipedia][German_Wikipedia]
[German_Wikipedia]: de.wikipedia.org
Link reference: German Wikipedia

Anchors
Take me to [Text](#text)

<a name="text"></a>Here comes the desired text
Take me to top of document

Take me to bottom of document

Add an Image as Link
![title](link)

Sample:
![GIYF](http://www.giyf.com/gfx/en/simpsons_board.gif)
Image:


Add an Image as Reference
![title][reference]
[reference]: link

Sample:
![GIYF][GIYF_reference]
[GIYF_reference]: http://www.giyf.com/gfx/en/simpsons_board.gif
Image:


Code
You can write code blocks by starting a line with 4 spaces:
<style type="text/css">
@media print {
    a[href]:after { content: " (" attr(href) ") "; }
    a[href] { font-weight:bold; text-decoration:underline; color:#06c; border:none; }
}
</style>
To mark a text as code (= print as is) you can use the backtick quotes: 
Use the `<p>` tag to begin a new paragraph in HTML.
Use the <p> tag to begin a new paragraph in HTML.
Code blocks can also be marked by backticks
```code```
or
```
code block
```
code
code block
Backticks can be marked as follows
`` `text` ``
`text`

Backslash Escape
\**no bold text\**
\__no bold text\__
\*italic\*
\_italic\_
*no bold text*, _no bold text_, *no italic*, _no italic_
Markdown provides backslash escapes for the following characters:
\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

Horizontal Ruler
A horizontal ruler can also be added by using 3 times * at the begin of a line:
***
or by 3 times - at the begin of a line:
---

Inline HTML
We can also use inline HTML, e.g. <b>bold</b> and <i>italic</i>. Or even a

link, e.g. <a href="https://www.google.com/">www.google.com</a>

Automatic Escaping for Special Characters
Ampersands (\&) in the text must be escaped to be used literaly

as ampersands. In links you doesn't need to escape them:
<https://www.google.com/search?site=&tbm=isch&source=hp&biw=1226&bih=860&q=reschensee+kirche&oq=Reschensee&gs_l=img.3.2.0l10.15389.17763.0.21464.10.8.0.2.2.0.134.706.6j2.8.0....0...1ac.1.64.img..0.10.743.4t07LS2GFec#tbm=isch&q=Stilfser+Joch>
https://www.google.com/search?site=&tbm=isch&source=hp&biw=1226&bih=860&q=reschensee+kirche&oq=Reschensee&gs_l=img.3.2.0l10.15389.17763.0.21464.10.8.0.2.2.0.134.706.6j2.8.0....0...1ac.1.64.img..0.10.743.4t07LS2GFec#tbm=isch&q=Stilfser+Joch
Also the entity 
&copy;
wont be changed and shown as copyright character in the browser: ©

Further Reading

Daring Fireball: Markdown
markdown.de German translation of the above site
Markdown Tutorial a short interactive tutorial
CommonMark A formal specification of the Markdown syntax
Pandoc the Pandoc software site (download/description)

Create a HTML5 Version With Pandoc
Pandoc converts different markup language into each other.
The easiest way to use Pandoc is the following command line:
pandoc --from=markdown_strict --to=html5 --standalone --metadata title="Markdown Introduction" --output=markdown.html markdown.md 
or
pandoc --from=markdown --to=html5 --standalone --output=markdown.html markdown.md
Hint: for larger input data you can split the content to several files and add all the

input file names to the command line to get one output file.
pandoc --from=markdown_strict --to=html5 --standalone --metadata title="Markdown Introduction" --output=markdown.html markdown_01.md markdown_02.md ...
Markdown to HTML5 Makefile
You can automate the convertion by creating a Makefile with the following

content
.SUFFIXES: .md .html
#
%.html: %.md
        pandoc --from=markdown_strict --to=html5 --standalone --metadata title=$* --output=$@ $<
#
clean:
    rm -f *.html
#
multisample.html: sample01.md \
    sample02.md \
    sample03.md
    pandoc --from=markdown_strict --to=html5 --standalone --metadata title="Sample Document from multiple Markdown documents" --output=$@ $^
The call
make markdown.html
will now create the file markdown.html from the file markdown.md.
The target multisample.html will create a new HTML file multisample.html from all the Markdown files

in the given order each time one of the Markdown files will change.
Further Pandoc Options
In certain cases it might be useful to have some more control over the

HTML file creation.
--toc
Add a TOC (table of content) at the begin of the HTML file.
--number-sections
Autonumber the headings (1, 1.1, 1.1.1, 1.1.1.1, 1.1.1.1.1, 1.1.1.1.1.1).
-H or --include-in-header
Add the given file at the end of the head section of the HTML file.
-H path-to-file/head.html
or
--include-in-header=path-to-file/head.html
To add some CSS or more metadata to your output you can use the

following data in a file with the option --include-in-header:
<style type="text/css">
    a[href]:after { content: " (" attr(href) ") "; }
    a[href] { font-weight:bold; text-decoration:underline; color:#06c; border:none; }
</style>
In the above example we make hyperlinks visible for printing.
-B or --include-before-body
The data from the file will be copied after the body Startelement (\<body>) of the

HTML file.
-B path-to-file/header.html
or
--include-before-body=path-to-file/header.html
-A or --include-after-body
The data from the file will be copied before the body Endelement (\</body>) of the

HTML file.
-A path-to-file/footer.html
or
--include-after-body=path-to-file/footer.html
Usage of the pandoc_title_block Extension
Optionally we can use the pandoc_title_block extension with the Markdown

format. With this extension we can use the following lines at the begin

of a file:
% title
% author(s) (separated by semicolons)
% date
Example:
% Markdown Sample Text  
% Author: Manfred Rosenboom (<a href="mailto:[email protected]">[email protected]</a>)  
% Last updated: <time datetime="2016-12-12T15:20:00+0100">Mon, 12 Dec 2016 15:20:00 CET</time>
This meta data will be used if we choose the from format markdown
pandoc --from=markdown --to=html5 --standalone --output=file.html file.md
<a name="bottom"></a>Pandoc and Encoding
Pandoc expects input data in UTF-8 encoding but the default Windows

encoding is still ISO Latin1. On Linux you can use Pandoc with such

encoded files with the following command
iconv -f latin1 -t utf-8 markdown_file.md | pandoc ...
The tool iconv is also available on Windows (e.g. with the

Cygwin distribution)
Best practice is to use UTF-8 encoded text files anyway - even under

Windows.