Creating Markdown Documents with ReText on Linux

The Markdown plain text format was created back in 2004 with the aim of getting authors to write using an easy-to-read document format that could also be converted into more complex forms like HTML or even PDF.

To make some text bold in a traditional document editor, you would select the text and then either use a keyboard shortcut or click on the relevant icon in the tool bar. In Markdown you just put ** before the text and ** after it. There are also conventions for italics, headings, and lists.

Although Markdown documents can be created in a normal text editor, there are also tools available which allow you to preview the document with all the effects applied and allow you to export the file in different formats. One such tool is ReText.

To install ReText on Ubuntu use the following command:

sudo apt-get install retext

You can run the program from the Launcher or by typing “retext” in a terminal window.

retext-via-launcher

The default layout is a simple text editor with a tool bar for common actions like Open and Save. At this point, you can start typing plain text. To mark some text as bold, use **, to mark it as italic, use a single asterisk (*), and to start a new paragraph, leave a blank line between one sentence and the next. In general, the text in the editor will remain plain, however for some formatting, most notably bold and italics, the editor will show the text (including the asterisk symbols) with the formatting applied.

retext-simple-usage

To see how the document would look in a more complex format, like HTML, click on the “Preview” icon in the tool bar. The main window will be replaced with a rendering of the document with the Markdown converted into HTML.

retext-preview

It is also possible to enable a “Live preview” where the window is split into two with one side showing the Markdown and the other side showing the rendered preview. To enable the “Live preview” mode, click on Edit in the menu bar and then on “Live preview.” Alternatively, use the keyboard shortcut “Ctrl + L.”

retext-live-preview

To mark a line of text as a header, you can either start the line with “#” or underline the text with “=” symbols, e.g.

This is a heading
============
 
# But so is this!
 
This is a sub-heading
--------------------
 
## And so it this!

retext-headings

You can also include HTML tags directly into the Markdown text. This gives you the flexibility to include almost anything you want; however, it does drastically reduce the readability of the plain text version of the document. Here is an example using the HTML tags for bold and center:

retext-html

Markdown files are saved using the “.mkd” extension. ReText can also export files as HTML, PDF, and ODT. The latter is the format used by suites such as OpenOffice and LibreOffice. To export a file, use the “File -> Export” menu.

Another useful option in ReText is the live spell checker. To enable it, click “Edit -> Spell check -> Enable.” Any words not in the checker’s dictionary will be underlined in red.

For a quick primer on Markdown, I would recommend this Markdown Cheatsheet. If you have any trouble using ReText, feel free to ask questions in the comments section below and we will see if we can help.