What is Markdown and how to use it

If you are a content creator and have not been living in a cave for the past fifteen years you should know the Markdown language. More importantly, you should know how to best use it.

If you don’t know, you are in the right place.

What is Markdown

Markdown is a markup language created in 2004 by John Gruber and Aaron Swartz.

Why create another markup language when HTML, LaTeX, and many others already existed?

Markdown is based on 3 principles:

1. immediacy
2. compatibility
3. longevity

Immediacy of Markdown

Gruber and Swartz’s objective was to enable less experienced users, having no web design nor formatting skills, to create formatted content.

In order to create HTML formatted content, the user must use a specific syntax and a set of over 100 elements called tags.

In contrast, text formatting in Markdown is much more straightforward. A text in Markdown is a file of simple text (plain text), in which the font size, color, or font does not change, as it does in Microsoft Word, for example.

The syntax is simpler, with no tags, and with a few symbols used to mark the function of the text.

Basic syntax can be learned in ten minutes.

For example, to write text in bold in HTML, you need to write as many as 17 characters, those corresponding to the strong tag: the opening tag should be enclosed in angle brackets (<…>), as should the closing tag, which also carries the backslash to indicate that it is indeed a closing tag (</…>).

<strong>Bold text</strong>

In Markdown, on the other hand, the characters needed are only 4, a pair of two asterisks:

**Bold text**

In some cases it is not necessary to insert any symbol.

While in HTML a paragraph should be indicated with the tag pair <p>...</p>, in Markdown you just need a blank line between paragraphs.

With these and other simple tricks, Markdown greatly simplifies the creation of formatted documents.

Not to mention that in a Markdown file you can always add parts of HTML code, which will be processed by Markdown as such.

Markdown compatibility

Markdown has another great virtue: *.md or *.markdown files can be converted to HTML and many other formats using a Markdown processor, a special program.

Another advantage is that – as *.md files are plain text files, that is, they can be opened with any text editor – they are not dependent on any particular software or application.

Unlike text files created by proprietary word processors, text files written in Markdown can be shared among different devices and systems.

Longevity of Markdown

Since Markdown files are not compiled, but are plain text files, it is reasonable to assume that computers will be able to read them for years to come.

Even if all programs using Markdown ceased to exist tomorrow (which is quite unlikely, given its widespread use) a user will still be able to access the contents of these files with any text editor (such as Windows Notepad, for example).

What Markdown is used for

In light of the above, it is no coincidence then that Markdown is becoming the writing standard for academics, researchers, content writers and bloggers.

Some sites such as GitHub, Reddit, Stack Exchange, OpenStreetMap or SourceForge have adopted Markdown syntax for user comments.

Markdown can be used in any situation where formatted text needs to be written.

It is often used to format README files in software development projects, to write posts in discussion forums, to write technical documentation, and to create articles and pages within web site creation tools, such as Grav, the CMS that was used to create Qabiria web site.

Many note-making and knowledge base programs use Markdown as their standard format, for example Obsidian.

The variants of Markdown

It may come as a surprise, but there is no defined standard for Markdown, with the exception of John Gruber’s original article, which nonetheless describes the language, leaving room for ambiguity and interpretation.

The official documentation on syntax does not address or vaguely addresses some issues, such as sublists, the “four-space” rule, and more.

As a result, several variants of the original language have arisen to overcome inconsistencies and errors in it, as well as adding new functions.

One of the most consistent standardization efforts is the one called Commonmark, which I invite you to learn about.

If you want to compare variants, you can turn to Babelmark which analyzes the output of the various implementations and highlights the differences.

In addition to the variants as such, a number of extensions have also sprung up, i.e., other languages that add new features to Markdown, such as tables, footnotes, lists of definitions, etc.

Some of these “extended” languages are:

• Markdown Extra
• GitHub Flavored Markdown (GFM)
• MultiMarkdown
• Maruku
• Kramdown
• Pandoc’s Markdown

What program to use to write in Markdown

As should be clear by now, any plain text editor works for writing in Markdown.

However, there are specific editors for all major operating systems. These editors usually allow you to preview formatted text with styles applied, that is, a rendered HTML version of what you are writing.

Emacs, gedit, vim, BBEdit and NotePad++ users can rely on specific plugins or even built-in functions to highlight the syntax of Markdown files and preview them.

In Notepad++ you can use the MarkdownViewer++ plugin to get a preview and be able to export the content to HTML or PDF.

A great online program for learning Markdown without having to install anything is Dillinger, a cloud-enabled, HTML5-based online Markdown editor. Dillinger also allows you to export files created in Markdown, HTML, and PDF.

Markdown basic syntax

Let us now look at the basic rules for formatting text in Markdown.

Italics and bold

To mark text as italic simply add an underscore or an asterisk before and after the text, leaving no spaces between the underscore (or asterisk) and the word, like this:

_text in italics_

*text in italics*

Similarly, to highlight a word or phrase in bold you must enclose it between 2 asterisks or underscores, as follows:

**text in bold**
__text in bold__

Strikethrough text

To cross out text, you have to enclose it between two pairs of tilde ~~ (in Windows you have to type ALT + 126 on the numeric keypad).

~~strikethrough text~~

Titles or headings

Titles can be formatted in two ways:

• by typing “equals” = sign or dashes in the line below the text, or
• preceding the text with one or more “hash” mark #, using one for first-level titles and more than one for lower-level titles. It is not necessary to “close” the text with another hash mark, but if you do so for aesthetic reasons, Markdown does not complain about it.

This is an example of the first way (called Setext):

This is a title that will be converted to H1
=============================================

This is a title that will be converted to H2
---------------------------------------------

While this is an example of the second way (called atx):

# This is an H1 title
## This is a H2 title
...
##### This is an H5 title

Paragraph

In Markdown, a paragraph consists of one or more consecutive lines of text separated by one or more blank lines. This paragraph will be separated from the rest by a hard return. If you want to insert a soft return, that is, a line break marked by the HTML <br /> tag, then simply insert two or more spaces at the end of a line before starting a new one.

Quotes

To highlight text as a quote, use the major symbol at the beginning of the paragraph. You can also nest citations inside each other using multiple symbols and even use other Markdown syntax within the citation, as shown in this example:

> This is a first-level quote.
> > This is a second-level quote.
>
> A **bold** is used here
> 
> ## And this is a title within a quote.

The style in which quotes will be displayed depends on the device, as well as the CSS associated with the HTML file produced.

Bulleted and numbered lists

To create a bulleted list, simply add an asterisk, plus symbol or dash to the beginning of the line, followed by a space and the list item.

To create a numbered list instead, you precede the text with a digit followed by a period, a space, and then the text.

The order chosen for the numbered list is indifferent and does not affect the result. That is, you can type 1. first item or 7. first item. The number that will appear on the page generated by Markdown will depend on the actual position of that item within the list and the first number used.

Here is an example:

* First item in a bulleted list
* Second item in a bulleted list
* Third item in a bulleted list

4. First item in a numbered list
1. Second item in a numbered list
2. Third item in a numbered list

The numbered list will show as follows:

4. First item in a numbered list
5. Second item in a numbered list
6. Third item in a numbered list

Programming code

To insert a code snippet into a Markdown document so that it appears as <pre><code>...</code></pre> you must insert four spaces at the beginning of the paragraph.

Another method is to use three grave accents (backtick) ` or three tilde ~ in a separate line to mark the beginning of the code and three more on another line to mark its end. For example:

```
print('Hello, world!')
```

Link

A special syntax is used to insert links: the text to be linked goes in square brackets and the URL goes immediately after (without separating space) in round brackets, possibly followed by the name of the link (which will become the value of the title attribute in the resulting HTML), as follows:

Here is an example of a [link](https://link.com "Link name")

Images

The images syntax is similar to that of links, but the pair of square and round brackets is preceded by an exclamation mark, as follows:

![Image description](/path/to/picture/img.jpg)

In the case of images, the text in square brackets will be displayed as the value of the img tag alt attribute.

Horizontal break lines

To insert a horizontal line, corresponding to the <hr /> tag in HTML, you must insert three or more dashes, asterisks or underscores on a separate line, separated by spaces.

For example, all of the following combinations...

* * *
---
- - -
****

they each generate a horizontal row:

---

---

---

---

Special characters

In some cases it is necessary to use the backslash character \ to generate literal characters that would otherwise be interpreted by Markdown as formatting syntax.

For example, if you want to enclose a word between asterisks you must use the backslash before the asterisks, otherwise the text would be interpreted as italics, like this:

\*text between asterisks\*

which results in *text between asterisks* and not text between asterisks (italics).

The same applies to other special characters, such as:

• Asterisk: *
• Dash: -
• Underscore: _
• Round brackets: ()
• Square brackets: []
• Brackets: {}
• Period: .
• Exclamation mark: !
• Hash: #
• Backtick: `
• Backslash: \

Note that writing these stand-alone characters does not require a backslash. It is needed only when they can be interpreted as formatting syntax.

How to translate Markdown files

But how do you translate text created in Markdown?

Since we are talking about text files, the easiest way is to open the *.md file with a text editor and manually translate it within the editor.

In this way, however, we cannot take advantage of all the translation resources available within an computer-aided translation program.

Translating Markdown files involves 2 main problems:

1. since there is no standard, the translation program or filter that interprets the file to be translated must take into account all possible variants and extensions which, however, are not all compatible with each other;
2. often programs using Markdown combine Markdown syntax with a header in YAML format (as is the case in Jekyll or Grav), so the program or filter must be able to interpret this header as well.

Markdown translation using Trados Studio

Perhaps the most popular computer-aided translation program, Trados Studio, as of version 2019 has a filter for Markdown files.

In the past, it was necessary to create a custom filter using a series of regular expressions.

The filter has some options, such as:

• considering line breaks as internal tags
• translating code blocks with an additional filter
• translating blocks of HTML code with an additional filter.

It is advisable to turn on at least this last option to get any HTML fragments used in Markdown files showing in the translation editor.

Markdown translation using Memsource

Memsource, one of the most popular translation management systems has a filter for translating Markdown files, which can then be imported and translated into Memsource without much complication.

Specifically, it presents the following options when importing the file to be translated:

• choosing the Markdown variant to be considered (Flavor)
• segmenting translation units at the hard retuns
• keeping white spaces in the translated document (i.e., spaces, line breaks, etc.)
• considering or disregarding YAML header (in case the header includes translatable text)
• importing code blocks (shows the code contained in the Markdown file in the translation)
• excluding code elements

You can also apply regular expressions to convert some text to tags, as well as set file elements to be converted to tags and even sections not to be imported.

Finally, you can define a list of characters that do not need to be escaped in the translated file.

Markdown translation using OmegaT

To translate Markdown files in OmegaT you can follow two paths:

1. use plain text file filter
2. use the Markdown file filter included in the Okapi plugin

The plain text file filter shows the entire contents of the file, so the translator must take special care not to distort the formatting syntax, any header, any HTML or other code in the text.

However, this option allows translators to manually edit the text with no limitation. This may be necessary when images or links other than the original ones need to be included in the translated version, or fields and values need to be added to the YAML header.

This option is therefore recommended in cases where the translator is familiar with Markdown and the structure of the original file.

Okapi’s Markdown file filter extracts translatable text from Markdown files. Since the different Markdown variants are not all mutually compatible, Okapi chose to design the filter to work with CommonMark, with some options that make it compatible with GitHub-flavored Markdown (GFM) as well.

More details about the filter can be found on the Okapi Wiki. Here suffice it to say that there is a parameter to include or exclude any YAML header from the translation, but it is disabled by default. As such, if you want to use options other than the default ones, you need to use Rainbow to create a file with the filter parameters, which will then need to be loaded into OmegaT.

What strategy to choose to translate Markdown files

The translation flow of a Markdown file depends not only on the system you use to translate it, but also on the program that generated and will have to interpret Markdown files.

Special attention should be paid to machine translation systems, because they do not always literally follow the syntax. For example, when translating content written in Markdown with Google Translate, the translation may have a number of grave accents that do not match the original, thus making the translated file useless.