Writing in Markdown

What is Markdown?

Let’s start with the Wikipedia definition:

Markdown is a lightweight markup language, originally created by John Gruber and Aaron Swartz, which aims for maximum readability and publishability in both its input and output forms, using plain text. Markdown converts marked text into well-formed XHTML documents.

The interesting thing about this language is that we can read documents in their original form or after they have been converted to HTML. Editing is much easier than writing HTML directly. Another advantage is that Markdown is quick to write because we do not have to take our hands off the keyboard. For that reason, I consider these languages the best choice for writing content for the web. In this blog, for example, I use Markdown to write posts thanks to the WP Markdown plugin. This is a fairly exhaustive review of Markdown syntax; the official English version is available on John Gruber’s site.

Where to write

Any text editor works for writing Markdown, although there are special applications that make the process a little easier. There are free options for the web, Windows, and Mac:

• Write MonkeyWIN
• Markdown PadWIN
• NVAltMAC
• CalepinWEB
• Hashify.meWEB

Arturo Goga published a video and a presentation that are very good for becoming familiar with the language. In this article, I will make a slightly more exhaustive review of the syntax.

Markdown syntax

There are several Markdown versions. After its publication in 2004, Michel Fortin developed an extended PHP version: Markdown PHP Extra, which added a few elements. I will review both here, since Fortin’s version has been widely adopted in MultiMarkdown, GFM, and sites such as Stack Overflow. Features only available in Markdown Extra are marked with an asterisk.

Paragraphs

Because readability is Markdown’s guiding principle, writing paragraphs does not require any syntax: we simply write. The only rule is that every new line becomes a new paragraph block, <p>. Within paragraphs, we can include tags such as <a>, <q>, <sub>, <sup>, and <abbr>.

Italics <em>

Within any line of text, we can add bold or italic emphasis. To make text italic, include an asterisk * or underscore _ before and after the word or words to highlight.

In this text, _these words are italic_.

Bold <strong>

To make text bold, use two characters instead of one—either asterisks or underscores.

In this other text, __these words are bold__.

Horizontal rules <hr />

To create a horizontal rule, we can use a sequence of asterisks * or hyphens -. There are several very visual options:

* * *

***

*********

- - -

---------

Abbreviations*

Markdown Extra makes it possible to create abbreviations. To do so, we declare them; every time the word HTML appears, it automatically creates an abbreviation:

<abbr title="Hyper Text Markup Language">HTML</abbr>

The syntax to define the abbreviation is:

*[HTML]: Hyper Text Markup Language

Afterward, anywhere in the text, we simply use the word without worrying about special syntax.

Headings

To write a heading, type the number sign # as many times as the heading level we want. For example:

# This is a level 1 heading
#### This is a level 4 heading

Alternatively, we can write h1 and h2 headings by adding any number of equal signs = or hyphens -, respectively, on the next line:

Heading 1
===
Heading 2
---

Headings with an id

In PHP Extra, we can also include an id by adding it after the title in braces, preceded by a number sign: {#id}.

Heading 1 {#id}
-------

If we want a table of contents or simply want to return to the heading, we can create a link like this:

[Link to the heading](#idHeading1)

Block quotes blockquote

To include these elements, we only need to put a greater-than sign > before each line. Nested block quotes are also allowed: add one sign for every level. They can also contain lists, code, and Markdown headings:

> Beginning of the quote
> > Nested quote
> ## Heading two
>
> 1. Numbered list
> 1. Numbered list, second item
>
>    code....

Hyperlinks

Hyperlinks are an essential part of hypertext, and I think Markdown has a very simple, intuitive syntax for adding them. There are two styles: inline and reference.

Inline

Links are declared within the same paragraph. The link text goes in square brackets [ ], while the URL goes immediately after it in parentheses (). We can also add a title attribute immediately after the URL, in quotation marks "".

[Link text](http://example.com "Title attribute message")

The downside is that the reading flow can get a little lost. To avoid that, we can use the following style.

Reference

This works much like footnotes, and the syntax resembles the inline style. In any paragraph, we put the link text in square brackets [ ], followed by an identifier—usually a number—also in square brackets:

[Link text][6]

At the end of the document, we add the id in square brackets [ ], followed by a colon :. Then we include the URL and title attribute. Optionally, we can wrap the URL in angle brackets < and >.

...goes at the end of the text,
[1]: http://example.com "Title attribute message"

If we want to omit the id, we can do so and use the bracketed text as the id:

[Example][]

Then define it as:

[Example]: http://example.com "Title attribute message"

Footnotes*

Footnotes are treated as hyperlinks within the same document. In Markdown Extra, we put a reference in the text with an identifier—usually a number—preceded by a caret and enclosed in square brackets: [^]. The definition can go anywhere in the document and is similar to links: it has the identifier, a colon, and the definition. The definition can contain Markdown block elements, but then it must be indented by four spaces.

[^1]: This is the text of my first footnote.
[^ref1]:
    In this second reference, which is longer, we use this syntax.
    It lets this paragraph be included in the reference too.

Images

Images have a syntax similar to hyperlinks and, like them, can be declared inline or by reference. The only addition is an exclamation mark at the beginning.

Inline example:

![Alternative text](/path/to/image.jpg "Optional title")

Reference example:

![Alternative text][id]
...
[id]: /path/to/image.jpg "Optional title"

Numbered and bulleted lists

Bulleted ul and numbered ol lists use the same syntax; only the initial symbol changes. For bulleted lists, we can use asterisks *, plus signs +, or hyphens - interchangeably. It is important to include a blank line before and after the list so it is interpreted correctly.

* Red
+ Green
- Blue

Numbered lists use a number followed by a period. They can be consecutive or simply repeat the same number:

1. Red
2. Green
5. Blue
1. Orange

List items can contain code, quotes, or paragraphs. The important detail is preserving the character each line begins with. More information is available in the official documentation.

Definition lists*

A great contribution from Markdown Extra is definition lists, <dl>, which let us define words and phrases much like a dictionary. To write one, add the word, then a line break; every line that belongs to that concept must start with a colon. Although the official documentation does not say so, I think indentation is optional. To start another definition, add an extra blank line.

Markdown
: It is a lightweight markup language originally created by John Gruber and Aaron Swartz that aims for maximum readability and publishability in both its input and output forms.
: Here we could add another definition of Markdown.

Code

To write code blocks, wrapped in <pre> and <code> tags, indent the text by at least four spaces or one tab:

<?php
   // Code goes here
?>

If we only want to write text inside a code tag, we can use it anywhere in the document, wrapped in backticks: `.

In this text, for example, tags such as `blockquote` and `em` are inside the "code" tag when interpreted.

Code in Markdown Extra

In Markdown Extra, we do not need to indent code blocks by four spaces. It offers another alternative: use at least three tildes ~~~ on a line before and after the block. This also lets us include lines before and after the code without Markdown removing them.

~~~
<?php
/*
* We can put any code here without indenting it
*/
echo ('it is easier');
~~~

Tables*

Markdown Extra lets us create simple tables. I think the syntax is very good because we can visually see a table, which follows Markdown’s philosophy.

| Column 1      | Column 2      |
| ------------- | ------------- |
| Cell 1, col 1 | Cell 2, col 2 |
| Cell 3, col 1 | Cell 3, col 2 |

Aligning the columns is not required, and neither is a pipe at the beginning or end of each row. This table would also be valid:

Day | Income | Expenses
--- | --- | ---
1 | $25000 | $50
2 | $200 | $320
3 | $5 | $50000

We can also add non-block Markdown elements: bold text, emphasis, links, images, and so on.

HTML elements

Tags that can appear within paragraphs or block elements can simply be written in the text: <a>, <img>, <sub>, <sup>, <code>, and so on.

If we do not want to use Markdown syntax, we can include images or links as if it were HTML, or even write <code> code inside tags</code>

In Markdown, we can add HTML tags such as <div>, <p>, and <table>, or even HTML5 tags such as <section>, <header>, and <footer>, which let us enrich the format. We only need to follow one rule: there must be at least one blank line before and after the text.

HTML elements in Markdown Extra

Although Markdown allows HTML tags, the text inside them is not interpreted. Markdown Extra removes that restriction as long as the markdown=1 attribute is added. With the WordPress plugin, markdown="block" is required. I think that, like required=required, it should be valid to write this attribute simply as markdown.

<section class="excerpt" markdown="1">
This text can also be interpreted by Markdown: we can write __bold text__ or another non-block element. The `markdown="1"` attribute is removed and the class remains.
</section>

The preceding text results in:

Things to consider

Markdown can sometimes confuse different block elements. To avoid that, it is a good idea to include blank lines before and after every element, especially lists. If we want to show a character reserved by Markdown, prefix it with a backslash \. The special characters are: