November 20, 2016

iA Writer IconiA Writer Icon

iA Writer 4 Adds to Markdown and Makes It Better

Product: iA Writer
Price: $9.99

iA has a tendency to take risks. They are the one developer who has consistently tried to improve the process of writing in plain text files.

The initial release included a custom version of the Nitti font, a startling blue caret, and a minimalistic aesthetic.

iA Writer Pro was their next attempt. I covered that here. It was an unsuccessful but commendable effort to bring some order to the process of writing.

iA Writer 3 was the next iteration. iA went back to the basics, they added the ability to manage your files in the file-system and brought full support of MultiMarkdown, including tables and footnotes. From Writer Pro, they brought along Syntax Control. And I wrote about it, iA Writer Grows Up in Meaningful Ways - iPadpedia.

We now have version 4 of iA Writer.

iA didn't disappoint this time either. They introduced something they are calling file referencing syntax. This is a proposed addition to the markdown specification. It is implemented in iA Writer, a better way of handling images, tables, and other files. It seems to be a reworking of the "transclusion" feature built into MultiMarkdown (thanks to Brett Terpstra for the background).

According to iA,

Every file reference you insert adds a block of content to your document, be it an image, table, or plain text file. These content blocks can then be ordered, stacked and chained with ease.

Long Documents

Markdown was designed for writing for the web. It's intent was to convert plain text into web ready formats for web publishing. That use case though still relevant has been augmented with people like me, using Markdown to write everything I write. Books, reports, long articles, and of course blog articles are all being written in Markdown and we are all running into the limitations of the original specification. There have been different attempts to address this problem. MultiMarkdown is one such attempt, Github Flavored Markdown is another, CommonMark is yet another. They are all involved in broadening the use cases of Markdown, or, trying to achieve some standardization in the implementation of the markup language.

iA has tried to tackle a different problem. How does one write a long document in text files?

The long document can be a book, an essay, or a report. Long documents are optimally written in parts. I am going to use an example of a novel to explain this. Novels are rarely written in a linear fashion. You don't start writing chapter one and end up in chapter fifteen in a linear fashion. What you do is write different chapters at different times and put them all together in book form at the end. That is the logic underlying the design of products like Scrivener and Ulysses. These products let you write in any order you want. Then arrange the content and compile into whatever final output you desire(.pdf, .docx, .html, .epub).

This is a difficult exercise to accomplish in text files alone. iA Writer is trying to tackle this problem.

The file reference syntax lets you specify that a text file is going to contain the contents of other text files. For instance, you can have an individual text file for every chapter of your novel, and compile them into one document by adding the file reference of the individual chapters into your master document. You export the content into a markdown file, an html file, a pdf file, a Microsoft Word file or a Project Archive. A Project Archive is a zipped file containing the markdown file and all of its associated content blocks.

The syntax for the file reference? Just a / mark followed by the name of the file you are including. Simple. The caveat is that the file must be in the same folder as the master file, or in a child folder of the folder that the master file is in. That is the only restriction.

Makes the process easy and an absolute boon to writers of long form documents. It is an elegant and simple solution to a problem which has plagued writers writing in text editors.


This file reference syntax also makes it possible to add images easily to your document. For instance, I will add a screenshot of this document.

File ReferenceFile Reference

This is the easiest way of adding images to markdown and definitely an improvement over the original Markdown specifications.


Tables in Markdown are difficult to create. I was going to Tables Generator to generate Markdown tables. I create them there and then paste them into my editor.

iA Writer 4 has made the process better. I can make my table in a spreadsheet. I can make it look the way I want and then export to a CSV file. You can just point iA Writer to the CSV file and now you have tables in Markdown. The syntax is the same for tables as it is for other text files and images. Since I use a lot of tables in my writing this is an absolute godsend.

Suggested Improvements

iA Writer is almost perfect in its present iteration but I have some nits to pick:

  1. When you export to a markdown file, the application insists on exporting a file with the extension, .txt. That doesn't make sense, why not use .md? (This is fixed in version 4.0.1)
  2. I would like an updated users manual or an updated help file. (Update: There is an updated help file, my system did not reach it.)
  3. Support for the use of tabs in macOS Sierra would be welcome. (Update: A bug in Night mode by Apple prevents this at this point. When and if Apple fixes the bug, it might or might not be implemented.)
  4. Support for relaunching the app with the documents which were open the last time the program was quit would be an improvement. (Update: This is a system preference. Go to General Preference Pane and uncheck Close windows when quitting an app.)
  5. Add keyboard commands to the items in the format menu without them. I have added them through the Shortcuts tab of the Keyboard preference pane.

Add Keyboard ShortcutsAdd Keyboard Shortcuts

I have asked for project support from iA Writer in the past. They have indirectly supported projects through the file reference syntax. You can make a folder and add all the files that are relevant to the current project in that folder. Makes using the file reference syntax easier and provides you a project folder. In addition, you can export your document and its ancillary files to a Project Archive which is a zipped file of all the content blocks relevant to a project.

One of my reasons for sticking with writing in Ulysses as opposed to moving to iA Writer was that iA Writer was missing support for user fonts and themes. It is true that I prefer Operator Mono over Nitti and I like Solarized as the theme when I am writing. However, I cannot recommend that iA Writer change this option. Nitti in iA Writer coupled with the blue caret is iconic to iA Writer. They should not change that. They have established a certain look and they own it, doesn't make sense to tinker with that one. The white and black screen for day and night mode are effective to soothe the strain in my eyes when staring at the screen for long periods of time, and I need to stop complaining about it.


So, have I moved all my writing to iA Writer? I have. I am going to give this move three months and at the end of that period I will re-evaluate whether the move away from Ulysses to iA Writer makes sense. The better support for Markdown and the file reference syntax which lets me add tables and images easily are the main reasons for the switch.

iA has done a stellar job of improving iA Writer with this version. If you write in Markdown, you owe it to yourself, to give this a try.

I recommend iA Writer 4 heartily.


  • Edited the suggestions for improvement section with feedback from developer.
  • Edited with suggestion implemented in version 4.0.1

macosxguru at the gmail thingie

macOS iA Writer Writing Markdown

Previous post
Dim Distractions With HazeOver HazeOver Product: HazeOver Price: $4.99 HazeOver is a distraction dimmer. I didn't think I needed it. I did. HazeOver Preference 1 When active,
Next post
Emacs Keyboard Commands Which Work in iA Writer Keyboard Command Behavior ⌃+K Deletes from the cursor to the end of the current line ⌃+O Inserts a new line after the cursor. The cursor