Content Blocks

On Mac, effortlessly insert images, text files, code, or CSV tables into your documents with Content Blocks.

Besides the integration of elements into your file, this feature also offers an excellent document management solution alongside the Table of Content or Library options like Favorites, Smart Folders, or Hashtags.

Content Blocks are popular with writers who need to compile the chapters of a book into a single document.

Origins of Content Blocks

John Gruber, one of the inventors of Markdown, remarked that image syntax was his biggest mistake with Markdown, and mentioned an alternative:

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

Looking for a syntax for file transclusion, we landed on what we call Content Blocks.

The Content Blocks feature was added to Writer a few years ago, if you want to know more about our journey with this, feel free to check our blog post from that time: iA Writer 4.

Adding Content Blocks

There are three ways to embed files in your document as Content Blocks. In all cases, the same principles should be followed:

• the Content Block must be at the start of an empty line
• embedded files should be referenced in iA Writer’s Library
• captions in quotes or parentheses can be added (this will be ignored with .txt files)

1. Drag and Drop

Simply drag and drop the file you would like to embed into your document opened in the Editor.

This can be done from iA Writer’s Library directly but also from Finder, or even your desktop (note that dragging a file onto the Editor adds a copy in the Library).

2. Typing Path

You can manually type the path of the file to embed in your target document. Be sure to respect the proper syntax, as below:

Section.txt "Section"
Balance Sheet.csv 'Finances'
images/Structure.jpg (Data Flow)

💡 Autocomplete will help find and add Content Blocks for you. To trigger autocomplete:

• type a slash /
• type a few letters of the file you’d like to add
• select the correct file and hit return

3. Format Menu or Command Palette

Choose Format → Add Content Block, or Add Content Block in the Command Palette (⇧⌘P), then choose the file you want to embed.

These embedded files are rendered in the Preview and will be included in documents exported to HTML, PDF, Markdown and Microsoft Word.

Content Blocks Metadata

You can add metadata to your content blocks, which is especially useful for images if you want to set a custom width or add alt text. Learn more about using Metadata.

Library