Markdown - the easier way to write html.

Writing articles in html by hand is quite annoying. Markdown helps writers by using a text format that prints well even without rendering it in the browser. It's the anti-markup, thus: markdown. I was amazed to learn that it's also available for python and that it supports syntax highlighting. Yes, you've guessed right, I'm using it here.

Basic Syntax.

Paragraphs are created automatically. An empty line or one filled with just spaces signals that a new paragraph should start. To force a line break, add two or more spaces at the end of that line. Text can be emphasized, printed in bold text or both by surrounding it with * or _ characters. But if you write down samples of code, you can preserve their original meaning (applies also to braces) by enclosing it in back quotes: `...` (that's usually just under ESCAPE on typical keyboards).

Posting links is easy. You can write them like so: <http://google.com>, which renders http://google.com (but you have to remember to include http(s)://, ftp(s):// or mailto:) or using [info text](http://google.com), which prints info text. Let's see how this text was written so far:

Paragraphs are created automatically. An empty line or one filled with just spaces 
signals that a new paragraph should start. To force a line break, add two or more 
spaces at the end of that line. Text can be *emphasized*, printed **in bold text** 
or ***both*** by surrounding it with `*` or `_` characters. 
But if you write down samples of code, you can preserve their original meaning 
(applies also to braces) by enclosing it in back quotes: `` `...`  `` 
(that's usually just under ESCAPE on typical keyboards).

Posting links is easy. You can write them like so: `<http://google.com>`, 
which renders <http://google.com> (but you have to remember to include 
http(s)://, ftp(s):// or mailto:) or using `[info text](http://google.com)`, which prints 
[info text](http://google.com). Let's see how this text was written so far:

You can quote using familiar, email-style >.

Some text.

> Quoted text
>
> Still the same quoted text, but new paragraph

>> A sub-quote.
>> Sub-quote continuation

> Main quote.

Which becomes:

Some text.

Quoted text

Still the same quoted text, but new paragraph

A sub-quote. Sub-quote continuation

Main quote.

Headers, horizontal rule.

There are two ways of creating headers. You can underline a line of text (or at least the first few characters) using ==== for H1 and ---- for H2. The other way is to add #, ##, ### etc. at the beginning of the line to get H1, H2, H3 etc. Just remember to leave the next line empty. Here is an example:

Main header.
============

H2 header.
------

Some text here.
More text.

## This is also a H2 header because there are two hashes.

Some text.

----

The line above is directly below an empty line, it will be rendered as a horizontal rule

Highlighted Code.

Regular Markdown expects you to indent each line of a code block with at least four spaces. Although it is readable, it's a lot of work if you post a big chunk of code. An easier way is made available by using the fenced-code extension. The block of code should be preceded and followed by a line of tildes (~), matching in length - at least 3 of them in a row. Example:

~~~~~~
code
~~~~
still same code
~~~~~~

It renders as:

code
~~~~
still same code

Both indenting and fenced code require that you leave at least one line before the code, and after the code empty. I've made a modification to fenced code, because originally it didn't highlight. The opening line of tildes can be followed by a dot and format short name as specified on this list. If you don't want automated formatting, write .text at the end of the fence line. To force the use of python lexer, write .py or .python, for example:

~~~~.py
def a(s):
    """a useless function"""
    return None
~~~~

will be seen as:

def a(s):
    """a useless function"""
    return None

Lists - the horror.

Lists are more tricky (it's easy to do them wrong). Items in unordered lists are signalled by hyphens or asterisks, while numbered items use numbers. There's a rule of 4 spaces of indentation on nested levels (sounds a damn lot like Python and PEP8). Better look at the original manual to see how lists work. Here is but a small example:

1.  Item one.
    Still item one.
2.  Item two.
    -  A sub-item. Notice the indent - 4 spaces!
    -  Another sub-item.
       This is still the same sub-item. 
    -  Another sub-item.
3.  Item three. One of the sub-items has 2 paragraphs, therefore we must
    add empty lines after item 3 and before item 4.

    -   A sub-item.
    -   Another sub-item. This is paragraph one.

        This is paragraph two. there are 8 spaces to the left!.

    -   Another sub-item.

 4. Item four.
 5. Item five, paragraph one.

    Second paragraph of the fifth item (4 spaces of indentation).

Something else.

Item one. Still item one.
Item two.
- A sub-item. Notice the indent - 4 spaces!
- Another sub-item. This is still the same sub-item.
- Another sub-item.
Item three. One of the sub-items has 2 paragraphs, therefore we must add empty lines after item 3 and before item 4.
- A sub-item.
- Another sub-item. This is paragraph one.
  
  This is paragraph two. there are 8 spaces to the left!.
- Another sub-item.
Item four.
Item five, paragraph one.

Second paragraph of the fifth item (4 spaces of indentation).

Something else.

Final notes.

There's a lot more to Markdown than I've posted here. Its creator has written good documentation on its syntax. I use markdown to write these articles, markdown is also enabled in comments (although without footnotes and not allowing html tags). For clarity I've blocked comments to this article, but you can try out Markdown without facing any consequences on the Markdown Battlefield.

Share this! Other articles