# Markdown Introduction
Author Manfred Rosenboom (maroph@gmail.com)
Last Update
License CC BY 4.0
--- # Introduction Let's begin with a quote of the [Markdown][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][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 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 --- ## 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 1. ordered subsublist * second element of an unordered list --- ## Automatic Link You can insert links directly in angle brackets to your text: The output in HTML will be similar to the following: https://www.google.com/ The output in HTML will be similar to the following: info@acme.com ## Link [title](link) Sample: [German Wikipedia](de.wikipedia.org) Link: [German Wikipedia](de.wikipedia.org). --- ## Link Reference [title][reference] [reference]: link Sample: [German Wikipedia][German_Wikipedia] [German_Wikipedia]: de.wikipedia.org Link reference: [German Wikipedia][German_Wikipedia] [German_Wikipedia]: de.wikipedia.org --- ### Anchors Take me to [Text](#text) Here comes the desired text Take me to [top of document](#top) Take me to [bottom of document](#bottom) --- ## Add an Image as Link ![title](link) Sample: ![GIYF](http://www.giyf.com/gfx/en/simpsons_board.gif) Image: ![GIYF](http://www.giyf.com/gfx/en/simpsons_board.gif) --- ## 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: ![GIYF][GIYF_reference] [GIYF_reference]: http://www.giyf.com/gfx/en/simpsons_board.gif --- ## Code You can write code blocks by starting a line with 4 spaces: To mark a text as code (= print as is) you can use the backtick quotes: Use the `

` tag to begin a new paragraph in HTML. Use the `

` 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. bold and italic. Or even a link, e.g. www.google.com --- ## 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: Also the entity © wont be changed and shown as copyright character in the browser: © --- # Further Reading * [Daring Fireball: Markdown][Markdown] * [markdown.de](http://markdown.de/) German translation of the above site * [Markdown Tutorial](http://www.markdowntutorial.com) a short interactive tutorial * [CommonMark][CommonMark] A formal specification of the Markdown syntax * [Pandoc][Pandoc] the Pandoc software site (download/description) [Markdown]: https://daringfireball.net/projects/markdown/ [CommonMark]: http://commonmark.org/ [Pandoc]: http://www.pandoc.org/ # 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: 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 (\) 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 (\) 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 (maroph@gmail.com) % Last updated: This meta data will be used if we choose the from format _markdown_ pandoc --from=markdown --to=html5 --standalone --output=file.html file.md ## 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](https://www.cygwin.com/) distribution) Best practice is to use UTF-8 encoded text files anyway - even under Windows.