Markdown syntax reference guide

Writer supports a subset of the Markdown formatting language. This lets you apply basic formatting by adding a few punctuation characters, such as *emphasis* and **importance**. It’s familiar, and in Writer for Mac, it’s also subtly formatted on-screen with Writer’s Auto Markdown.

(Auto Markdown is not available in Writer for iPad and iPhone… yet. You can preview formatting via Share > Preview.)

Headings

  • # Title = First level heading
  • ## Title = Second level heading
  • ### Title = Third level heading

…up to six levels

Emphasis and Importance

  • Emphasis: *example* or _example_ (Command-I in Writer for Mac)
  • Importance: **example** or __example__ (Command-B in Writer for Mac)

Lists

Numbered lists: type 1. then a space

1. Ordered list item
2. Ordered list item
3. Ordered list item

Any number (followed by a full stop and space) can be used — list items will be ordered from 1 when exported.

Bulleted lists: type \*, - or + then a space

Create a bulleted list by using an asterisk (*), hyphen (-), or plus sign (+), followed by a space. For example:

* Bulleted list item
* Bulleted list item
* Bulleted list item

Nesting lists

You can also nest lists several levels deep, and combine them:

* First level
** Second level

1. First level
1.1. Second level

* First level unordered list item
* 1. Second level ordered list item

Using tab indents for nesting is also possible when using a physical keyboard, but currently there is no Tab key in the iOS on-screen keyboard, and Auto Markdown is optimized for non-tab nested lists.

* First level
    * Second level

1. First level
    1. Second level

Blockquotes

Type > plus a space (just like email):

> A quoted paragraph
>> A quoted paragraph inside a quotation

Create a link by surrounding the link text in square brackets, followed immediately by the URL in parentheses:

[text to link](http://example.com/)

New: In Writer for Mac 1.5 you can also use reference links. Add the reference in square brackets after the text to link. Then, on a line by itself add the reference with a colon, space, and the URL:

[text to link][ref]
…
[ref]: http://example.com/

Images

New: In Writer for Mac 1.5 you can add also images via the following syntax:

![alt text for image](http://example.com/image.jpg)

Currently only web-accessible image URLs are supported. On export to RTF or .docx, currently the image’s alt text is added, but the image is not embedded.

Code

You can mark up code in-line using backticks (`code`), or add a code block by adding at least four spaces to the start of a line:

This is a code block

It’s also possible to start a code block with a tab, as long as the text doesn’t start with list, header or blockquote syntax characters (1., *, -, +, #, >).

Note that inline formatting characters (like _underscores_) are ignored in code.

Separating paragraphs

A line starting with a tab indicates a block of code. Because of this it is currently not possible to use a return-plus-tab to indicate a new paragraph in Writer. Instead, please use one or two returns to separate paragraphs.

Horizontal rules

You can add a thematic break which will be represented by a dividing line (<hr>) when exported to HTML. To do so, add three or more asterisks (*), hyphens (-), or underscores (_) on a line by themselves, optionally separated with spaces. For example:

* * *

or

-------------

“Escaping” formatting characters

If you want to type a formatting character and have Writer treat it as text not formatting, type a backslash first \. This means \* gives *, \_ gives _ etc. Escaping isn’t needed in code blocks.

Exporting

Writer supports exporting as HTML, RTF, and Microsoft Word 2007 (.docx) via File > Export. For more information on the “Export As” option, please see “Markdown syntax differences” below.

You can export as PDF via File > Print > PDF, as formatted or unformatted text.

Finally, you can copy formatted text from Writer’s Preview to paste into other programs.

In addition to Writer’s export options, you can also convert Markdown to other formats using programs such as Marked for Mac and Pandoc. If anything doesn’t work as expected, please let us know.

Markdown syntax differences

iA Writer’s default syntax (Writedown, or Writer-flavored Markdown) includes some minor changes from Markdown. These include:

  • Only a single return is needed between paragraphs.
  • Nested list items use additional list syntax (** list item), rather than tab indentation (    * list item).
  • Not all Markdown syntax is supported.

Preview in all versions of Writer, and Copy HTML and Import in Writer for Mac, default to this syntax. However, you can choose Writedown or original Markdown syntax when exporting in Writer for Mac 1.5 via the Export As: pulldown in the Export dialog.

In Writer for Mac 1.4, the export dialog had a “Strict Markdown” setting which changes whether a single or double return is needed between paragraphs.

Other formatting syntaxes

Markdown, MultiMarkdown, and other plain text syntaxes contain additional formatting, such as for footnotes. While Writer uses the syntax above by default, you can use “vanilla” Markdown on export, and you can use any plain text syntax in Writer, together with other programs for preview and export.