We’ve been hard at work producing the next major update to iA Writer, and we’re happy to announce its arrival. iA Writer 4 adds a whole new dimension to how you can work with your documents. We’re excited—and a little nervous—to unveil how this all works…

What did we all want?

We receive feature requests for iA Writer everyday. These cover a whole spectrum of what is or could be possible in the apps. We create highly focused software and analyzing the trends of user requests helps our understanding on where we need to improve. It was clear everyone wanted:

  1. A better way to work with longer texts
  2. Full support for images

Long-Form Text Structure

We’re fully committed to the plain text format. We covered much of our thinking surrounding past, contemporary and future proof text formats in our post on multichannel text processing.

How do you structure, link, nest, and organize long form text, in plain text? There are only two ways: Either you use an existing light Markup or you create one. We figured simply adding file names could do the trick. This would let us move blocks of content around without losing the benefit of the raw format. The established method of transclusion1 seemed to be the way forward, but every implementation we could find relied on cryptic characters:


While considering the best syntax to use, we came across a comment from John Gruber. He remarked image syntax was his biggest mistake with Markdown2, and mentioned an alternative3:

My best idea for good Markdown img syntax would be to just paste in a URL ending in .jpg/.png/.gif etc.

We liked the idea.

Images in Plain Text

To add an image in iA Writer 4, write the path on an empty line:


For image captions, use quotes or parenthesis:


The format works just as well for other file types…


Markdown tables are painful to write manually. On the other hand, spreadsheet editors like Numbers or Excel make it easy to create tables with complex formulas. A long-time standard for exporting these tables is the comma separated value format (csv). You can compose a table in Excel, and then have all the calculations exported in a plain text csv. And now you can reference a csv file in iA Writer the same as way as images:


Using the first prototype simulating said behavior, we knew this was the way forward. It’s hard to describe how transclusion feels other than it just feels right. Beginning with a simple, straightforward syntax kept reaping dividends.

Text in Text in Text…

Before all this, for quite some time, we had been independently developing a concept that we called inception. We joked about it internally, as it reminded us of a popular Internet meme.


Much later we discovered that it already had a name: transclusion. Transclusion was first described by Ted Nelson, the father of Hypertext. Put simply, transclusion is a way of directly embedding text in text without redundancy.

“…transclusion means that part of a document may be in several places—in other documents besides the original—without actually being copied there.”4

With this newly discovered concept in hand, we slowly realized its potential beyond simple embedding.


It’s possible to embed pictures, tables and text. Nesting and embedding text doesn’t stop at a single level.

  • A book can be built from chapters
  • A chapter can also be built from several sections
  • Sections can be built around text snippets consisting of single quotes
  • The same quotes can be reused throughout the same text body

Repeat this process of text inception as long as your sanity holds.

Content Blocks

We’ve made a swath of improvements in iA Writer 4. The meat on the bone is this new file referencing syntax. 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.

We think this syntax is a natural extension to Markdown, and it would please us to see other apps use it too. We’re a bit nervous since it’s a deviation, but we’d still like to try it out and hope it finds friends. We’ve published an introductory spec on GitHub to get the ball rolling. Hopefully, Content Blocks based on file transclusion will become a thing beyond iA Writer. One day all Markdown editors may work like that, but, as IBM famously said, why wait?

  1. Transclusion (Wikipedia) 
  2. John Gruber’s Tweet 
  3. John Gruber’s Tweet 
  4. Theodor Holm, Literary Machines, The Report on, and of, Project Xanadu, 1992. Preface.