Illustrated Examples Of How To Create HTML, EPUB and PDF's With Markdown

10 minute read Published:

A modern guide for writing markdown.


Do you dream of self-publishing on Amazon Kindle? Or creating content for a static website built on the modern web development architecture of the JAMstack?


Markdown has been gaining traction due to it’s simple syntax and ease of use. Markdown markup is easily readable and practically publishable as plain text, unlike it’s HTML counterpart, bound to it’s native taggy surrounds. Pandoc is the swiss-army knife and will reliably convert into HTML, pdf, epub, wiki or myriad of other formats. You can give markdown a try. Thankfully, you don’t have to to learn HTML anymore to publish for the web.


Handy Reminder: HTML is awesome because of the ability to zoom in and out with most any display; hold down ctrl and = or - to adjust font-sizes. Alternatively there's ctrl'n scroll'n; hold down the ctrl key and scroll your mousewheel.


Markdown’s syntax has been influenced by several existing text-to-html filters such as setext, atx, textile, restructuredtext, grutatext, and ettext – the single biggest source of inspiration for markdown’s syntax is the format of plain text email. Full disclosure: this tutorial is based on the original spec from 2004.


Okay, now that we’ve tipped our hats to history, all you need to get started is a plain text editor such as Notepad++, Atom, SublimeText or Vim. Note: you don’t want to use a word processor, that would add extraneous characters. You can view the results of your markup (save it with the .md extension) by opening your document in Firefox, Opera, Safari, Chrome or if you’re a geek, in a color-coded terminal-based browser such as Lynx. All set:


type this:

Largest font
============

to produce this:

Largest font

similarly,

Elements
--------

or

## Elements

and we get

Elements

Type

### Links

to produce

…and so on down the line to ###### which produces the smallest header a.k.a. H6


A links’ text is delimited by square brackets immediately followed by parentheses enclosing the url that the link points to.

A [generic](http://example.com/) link.

will produce


A generic link.


Not that you want to go before my fascinating tutorial is over! To provide a link lower down on the page, the following will do the trick.


__Take me to the__ [Coloured Code](#Coloured_Code)

Take me to the Coloured Code


Much More Than Meets The Eye: Most HTML is obscured from the reader, and also to a lesser extent the markdown that underlies this page. Javascript and other platform-specific components can add functionality to otherwise static webpages.


The following can be written in HTML or markdown as we have seen. It’s both an anchor and a header.

<h3 id="Emphasis">Emphasis</h3>

Emphasis

Markdown treats asterisks (*) and underscores (_) as indicators of emphasis. Text wrapped with one * or _ is the equivalent of using HTML <em> tag. Double them up and text will be wrapped with an HTML <strong> tag like so:

*single asterisks*

single asterisks

_single underscores_

single underscores

**double asterisks**

double asterisks

__double underscores__

double underscores

~~strikethrough~~

strikethrough

Lists

Markdown supports ordered (numbered) and unordered (bulleted) lists.

Unordered lists can use asterisks or pluses or hyphens interchangably as list markers when followed by a space:

*   apples
+   peaches
-   cherries

produces:

  • apples
  • peaches
  • cherries

Ordered lists use numbers followed by periods followed by a space and the list item. the actual numbers you use to mark the list have no effect on the HTML output. you could even jumble up the numbers and it would still produce an ordered list:

2. Scooby
1. Dooby
4. Do

produces:

  1. Scooby
  2. Dooby
  3. Do

List items may consist of multiple paragraphs. Paragraphs can be neatly wrapped with hanging indents of 4 spaces. Or your notes can be as messy as mine. Order will be available when the markdown has been interpereted.If subsequent paragraphs in a list item are indented by either 4 spaces (or one tab) they will be included in the bulleted paragraph:

*   If something can go wrong, it will.
    If anything simply cannot go wrong, it will anyway.
    Left to themselves, things tend to go from bad to worse.
-     The opulence of the front office decor varies
inversely with the
fundamental solvency of the firm.
      The chance of the bread falling with the buttered side down being directly proportional to the cost of the carpet.
* Tell a man there are 300 billion stars in the universe and he'll believe you. Tell him a bench has wet paint on it and he'll have to touch to be sure.
  • If something can go wrong, it will. If anything simply cannot go wrong, it will anyway. Left to themselves, things tend to go from bad to worse.
  • The opulence of the front office decor varies inversely with the fundamental solvency of the firm. The chance of the bread falling with the buttered side down being directly proportional to the cost of the carpet.
  • Tell a man there are 300 billion stars in the universe and he’ll believe you. Tell him a bench has wet paint on it and he’ll have to touch to be sure.

To put a blockquote within a list item, the blockquote’s > delimiters need to be indented:

*   Listen, trust, do:

    > The only thing more important than your to-do list is your to-be list. The only thing more important than your to-be list is to be.”
― Alan Cohen

* We will never finish everything on our to-do lists. Such is life!
* Write another to-do list.

produces:

  • Listen, trust, do:

    The only thing more important than your to-do list is your to-be list. The only thing more important than your to-be list is to be.” ― Alan Cohen

  • We will never finish everything on our to-do lists.

  • Write another to-do list.

Emoji

I enabled emojis in my [hugo] config file with enableEmoji = true. I was going for :thinking_face: but apparently that one isn’t supported yet (your mileage may vary). Instead, I present japanese_ogre.


👹

Inline Code

To highlight a single code command surrounded by ordinary text, wrap it with backtick quotes (`). Unlike a pre-formatted code block, a code span indicates code within a normal paragraph. It will be shown in the ‘mono’ font of the terminal: Delimiters need to be indented:

Use the `printf()` function.

produces:


Use the printf() function.


This snippet of HTML code is an anchor or an embedded id and a H3 header. A TOC, or table of contents, uses internal page links. It could also be written in markdown, same difference! (The HTML tags get added when the page is run through a processor):

[*Coloured_Code*](#Coloured Code)
<h3 id="Coloured_Code">Coloured Code</h3>
<!---hidden comment: I like the old spelling (shrugs)--->

Coloured Code

Nowadays there is support for code highlighting for about 160 programming languages. this example is written in bash, the commandline language of the linux shell. In addition to the three backticks you can add an abbreviation such as md (markdown) or sh (to highlight code written in bash). I’ll show the backticks that are required to create a code box (they are just for illustration and have to be escaped by \ so as not to be interpreted as ‘special characters’).

\```sh
# To load nvm bash_completion upon login or when the file is sourced.
# add these lines to your `~/.bashrc`, `~/.profile`, or `~/.zshrc` config file
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # this loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
\```

The ‘Emphasis’ header/anchor was created using a HTML snippet, but we can also get around using markdown:

[*back up to where I was*](#Emphasis)

back up to where I was

Images

To insert images to your markdown file, use the markup ![alt](/path/image.ext). the path can either be relative to the website, or a full url for an external image. Below is a screenshot of my current desktop.


![Semantic description of image](/images/path/to/folder/image.png "Image Title")

a.k.a.

![A screenshot of the underlying code](/images/md-guide.png "Neovim on My Desktop")

A screenshot of the underlying code


Cool Tip: Set your program windows to 70% transparency in linux. The top layer shows my text editor, neovim, underneath is the HTML translation in firefox. On the bottom layer, a random slide-show of hand-picked artwork.

Video

There are a couple of ways to share a video. I can use a shortcode provided in the [Hugo] static site generator. Plain markdown results in a link to the video, but with HTML5 tags we can embed this video of the author making fruit leather with a homemade solar dehydrator.:

<iframe width="1059" height="480" src="https://www.youtube.com/embed/aVHsUCALkoU" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>


Paragraphs and Line Breaks

A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. Normal paragraphs should not be indented with spaces or tabs.

If you want to be sure of getting empty lines between elements, insert a <br /> break tag to be certain of making blank lines.

Tables

| Left         | Center        | Right          |
| :----------- | :-----------: | -------------: |
| This         | This          | This           |
| column       | column        | column         |
| will         | will          | will           |
| be bold &    | be            | be             |
| left-        | center-       | right-         |
| aligned      | aligned       | aligned        |
Left Center Right
This This This
column column column
will will will
be bold & be be
left- center- right-
aligned aligned aligned

If you want to format text on a particular way on the page, one way to do it is create a table with those proportions (your table will span the width of the page). Set the border of the table to 0px in your CSS and the table edges will not be visible, but the text will.

Blockquotes

Markdown uses email-style > characters for blockquoting. Blockquotes can contain other Markdown elements, including headers, lists, and code blocks. Put > before the first line of a hard-wrapped paragraph:

>    Sorrow prepares you for joy. It violently sweeps everything out of
>  your house, so that new joy can find space to enter.
>  It shakes the yellow leaves from the bough of your heart, so that fresh,
>  green leaves can grow in their place. It pulls up the rotten roots,
>  so that new roots hidden beneath have room to grow.
>  Whatever sorrow shakes from your heart, far better things will take their place.
<br>
>    ~Rumi


Sorrow prepares you for joy. It violently sweeps everything out of your house, so that new joy can find space to enter. It shakes the yellow leaves from the bough of your heart, so that fresh, green leaves can grow in their place. It pulls up the rotten roots, so that new roots hidden beneath have room to grow. Whatever sorrow shakes from your heart, far better things will take their place.
~Rumi


Code Blocks

Pre-formatted code blocks are used for writing about programming and source code. Rather than forming normal paragraphs, the lines are wrapped in <pre> and <code> HTML tags to be interpreted literally. To get the result, indent every line of the block by at least 4 spaces or 1 tab.

    <div class="footer">
        &copy; 2004 foo corporation
    </div>

will produce this:

<div class="footer">
    &copy; 2004 foo corporation
</div>


A code block continues until it reaches a line that is not indented (or the end of the article). To put a code block in a list, the code block needs to be indented twice – 8 spaces or two tabs.


Backslash Escapes

Regular markdown syntax is not processed within code blocks. e.g., asterisks are just literal asterisks within a code block. This means it’s also easy to use markdown to write about markdown’s own syntax. Outside of code blocks you can use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown’s formatting syntax. For example, if you wanted to surround a word with literal asterisks (instead of an HTML tag), you can use backslashes before the asterisks, like this:

\*literal asterisks\*

*literal asterisks*


Escape the following character with backslashes when you want to be sure they’re interpereted literally:

\ backslash ` backtick * asterisk _ underscore {} curly braces [] square brackets () parentheses # hash mark + plus sign - minus sign (hyphen) . dot ! exclamation mark


Lines across the page with either of:

***
---


This guide is also available on Github


Home

comments powered by Disqus