Our apps use Markdown formatting. This lets you apply basic formatting by adding a few punctuation characters. You can also use the formatting buttons in the bottom bar of your text window on OS X or the formatting keys in the Keyboard Bar of iA Writer for iOS.
Markdown Guide
1.4.1. Basics
If you are not familiar with Markdown, it might look a little scary at first. Once you get the basics, you will quickly love it as it allows you to format your text without taking your hands off the keyboard. iA Writer’s Auto-Markdown will give you instant feedback if you got the formatting right or not.
Headings
You can use up to up to six levels by writing # at the start of a line; the number of hashtags defines the hierarchy of the heading.
# First level heading
## Second level heading
### Third level heading
Emphasis and Importance
Emphasis (“italics”) and important (“bold”) are written by putting * or _ around the text you want to see in a different format.
- Emphasis:
*example*or_example_(⌘I) - Importance:
**example**or__example__(⌘B) - Emphasis + Importance
***example***or___example___
Numbered lists
Type 1. then a space. Any number (followed by a full stop and space) can be used and the list items will be ordered from 1 when exported.
1. Ordered list item
2. Ordered list item
3. Ordered list item
Bulleted lists
Type *, - or + then a space. Create a bulleted list by using an asterisk (*), hyphen (-), or plus sign (+), followed by a space.
* Bulleted list item
* Bulleted list item
* Bulleted list item
Task lists
Type -[ ] or 1.[ ] then a space. Adding an x between the square brackets will tick off a task list item in the Preview. iA Writer for Mac and iOS also support clicking or tapping the list item marker to toggle it.
- [ ] Unfinished task list item
- [x] Finished task list item
Nesting lists
You can 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.
iA Writer for iOS includes keys to indent and outdent list items. They can be found by tapping and holding the list key in the keyboard bar.
* 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
1.4.2. Advanced
Links
Create a link by surrounding the link text in square brackets, followed immediately by the URL in parentheses:
[text to link](http://example.com/)
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
Both local and web URLs are supported. On export to .docx, currently the image’s alt text is added, but the image is not embedded. Markdown uses the following syntax for images:
When using local images, they must be in a folder added as a Library location. This gives iA Writer permission to use the file. Folders can be added to the Library in Preferences on Mac.
On iOS, only images in the iCloud Library are currently supported.
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
In iA Writer, 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., *, -, +, #, >).
In addition, you can use Fenced code blocks, which begin and end with triple backticks, and don’t need indenting. Note that inline formatting (like _underscores_) is ignored in code.
```
This is a fenced code block
```
Footnotes
Add a footnote in square brackets preceded by a caret. Then add the footnote content like a reference link, for example:
Some text with a footnote[^1].
…
[^1]: The linked footnote appears at the end of the document.
You can also add an inline footnote in the following manner:
Some text with a footnote[^This is the footnote itself.].
Table of Contents
Generating a table of content is as easy as it gets. Just add {{TOC}} wherever you want the table of content to appear and iA Writer generates it from the Headlines you use in your text. There is a custom key for it on iOS.
On Mac you can add it via the toolbar or the Format Menu. The TOC will become visible and clickable in preview.
Tables
To make a table, use vertical bar characters to denote cells. Start with column headers, separate with a row of cells with hyphens, then add further rows of cells. For example:
|Header |Column 1 | Column 2 | Column 3 |
|:--- |:---- |:----:| ----:|
|1. Row| is | is | is |
|2. Row| left | nicely | right |
|3. Row| aligned | centered | aligned |
Let’s be real. This is a mess. Markdown tables look more reasonable than HTML-Tables, but they are the weak point of Markdown. That being said, they still translate nicely when rendered:
| Header | Column 1 | Column 2 | Column 3 |
|---|---|---|---|
| 1. Row | is | is | is |
| 2. Row | left | nicely | right |
| 3. Row | aligned | centered | aligned |
There is a trick though you can use when writing Markdown tables with a monospaced font. You can feign the correct column width by adding space characters to align the table:
Note: If you find your table does not render correctly in Preview, please ensure Smart Dashes are turned off in Edit → Substitutions.
iA Writer for Mac includes a button in the Toolbar which will automatically generate the cells for a table. This is also included as a key in iA Writer for iOS’s keyboard bar.
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.
Line breaks
From the Markdown specification:
When you do want to insert a
<br />break tag using Markdown, you end a line with two or more spaces, then type return.
iA Writer also allows you to insert a <br /> into a paragraph by using Shift+Enter. This will add the spaces required at the end of the line for you.
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.
1.4.3. MultiMarkdown
Writer apps currently use MultiMarkdown. In addition, Writer’s default syntax includes some minor changes. These include:
- Only a single return is needed between paragraphs.
- Nested list items can use additional list syntax (
** list item), in addition to “default” tab indentation (* list item).
In iA Writer, you can change these syntax modifications from on to off in the Preferences.
Metadata
Use MultiMarkdown’s metadata to store important information about your documents, hidden from Preview. To start using metadata in your documents, turn on “Process Metadata” in Preferences.
You can use MultiMarkdown metadata to build correspondence Templates.
You can do this with two easy steps. First you define your Metadata at the very top of your document, followed by an empty line. Let’s write “The Cat sat on the Mat” with Metadata. Write:
Animal: Cat
Thing: Mat
You can use the metadata in the text by putting it in brackets adding a % sign. Write:
The [%Animal] sat on the [%Thing].
The whole document should now look like this:
Animal: Cat
Thing: Mat
The [%Animal] sat on the [%Thing].
If you open Preview and compare the raw text and the rendered Markdown you will see this:
1.4.4. Preview
Writer apps use Markdown formatting, so you can format your text just by typing. It’s familiar, and it’s also subtly formatted on-screen using Auto Markdown:
Writer also provides a formatted preview of your document:
- iA Writer for Mac: choose
View→Show Preview(⌘R) or swipe to the left - iA Writer for iPad and iPhone: tap
Previewor swipe to the left
1.4.5. Exporting
iA Writer supports exporting as plain text, HTML, Microsoft Word 2007 (.docx), and PDF via File → Export. You can also export as PDF on Mac via File → Print → PDF, or File → Print Plain Text → PDF .
Finally, you can copy formatted text from Writer’s Preview to paste into other programs.
