Substance Composer User Manual

Substance Composer is a modern workspace for creating professional web-first publications. The app works similarly to traditional word processors. There is one important difference though: Substance Composer urges you to focus only on your writing, not on its layout.


First you need to download and install the Substance Composer on your computer.


Extract the contents of the zip file and drag Substance to your Applications folder.


Execute setup.exe and follow the installation instructions.


Linux version is available. Installation instructions are coming soon.

Your first Substance article

Open Substance Composer. You will be greeted by a blank document.
A blank Substance document
Move the cursor using mouse or arrow keys, and enter text as you would in any text editing environment.

Emphasize your text

We provide a limited set of annotations to emphasize your content with different semantics. Use the annotation toolbar on the uper right of the content panel to do so.

Add structure

Use the text transform tool on the upper left to turn a paragraph into a heading in order to structure your document. To change the level of a heading you can also use TAB and Shift+TAB keyboard shortcuts.

Add figures

Click the Figure button in the toolbar which shows a file select dialog. Pick the image you want to add and confirm. The image will be attached to the document. We don't have any restrictions on the size of the image. Just make sure your images aren't too large, so they load fast enough once published to the web.

Add videos

You can easily embed videos in your publication. Substance supports modern HTML5 video formats.
Adding a video to your publication
Unfortunately, browsers support different encodings for video playback. We recommend to use a combination of MP4 (h264) and OGG or MP4 (h264) and WebM for maximum browser compatibility. There are a number of video converters our there that you can use to prepare your video in different encodings. We have used Miro Video Converter to prepare MP4 and WebM versions of a video. You can also set a poster image, which is shown as a placeholder before the video is played by the reader of your article.
Converting a video file to the open WebM format
Please note, that due to licensing issues MP4 files can't be played within the Composer. However, they will work once you have exported your publication and open it in a web browser.

Add audio

Similar to video you can also include sound files in your documents.
Adding audio to your publication
Please note that due to licensing issues MP3 files can't be played within the Composer. However they will work fine when viewed in a regular web browser.

Add web pages

It is possible to embed any HTML webpage into your document. That way you can deal with missing node types, such as tables, visualizations etc. However there are a few things you should know:
Substance documents are self-contained, so ideally your embedded HTML page does not link to external resources (images etc.). You can use them, but then readers won't be able to view that content offline. Also, it is impossible for Substance Composer to determine the dimensions of the iFrame used in the document. So you have to set the width and height explicitly on the body element of the web page that you want to embed. Here's a sample HTML page that can be handled by the Composer.
<body data-width="300px" data-height="400px">
    <tr><td>Wheel</td><td>$ 45.49</td></tr>
    <tr><td>Brakes</td><td>$ 145.49</td></tr>

Add remarks

You can easily add remarks and errors by clicking the toggles on the top right of the content toolbar.


Substance Composer supports an offline review workflow. You can send your-document.sdf to a friend and let them review your content. They'll be able to add remarks and corrections, but also edit the text itself.
An error annotation highlighting a typo
Sunstance Composer doesn't yet support online collaboration. However, you can share documents in a Dropbox or Google Drive folder, so that your co-authors and editors can access and modify them.

Publish Yourself

Your document can be turned into an interactive web publication at any time. Click Publish on the top right to see a preview.
The Publish shows a preview of your final web publication.
Click Export as a web page in the Publish dialog or use File -> Export. Select a folder on your hard disk, where your publication gets stored temporarily. Use a web-compatible name without spaces and special characters (e.g. my-first-substance-article would be a good one).

Control your own webspace

With Substance we want to encourage you to create your own webspace on the Internet where you can put your writing. It is tempting and convenient to use hosted web publishing solutions. However, by using these 1-click publishing services, you also lose control of your data and give up a fair bit of freedom. If you do not have a webspace yet, we recommend using (it's free for low traffic sites). Consider supporting local independent hosting providers in your area, and helping to keep the Internet equally distributed. After all, any webhosting service works, the choice is up to you.

Upload using SFTP

Many webhosting services support secure file transfer protocol (SFTP) for uploading content to your webspace. To upload content in this way, you will need an application which supports SFTP. One such freely availble application for Mac OS X and Windows is Cyberduck. An alternative for Windows users is WinSCP, and there are many others available as well.
First connect to your webspace:
In Cyberduck's connection dialog select SFTP, enter your webspace's credentials and hit Connect.
Once connected you can upload your publication.
In Cyberduck just drag and drop the folder on the application to upload.
Finally you should be able to access your publication on the web on


Substance has support for theming. You can develop completely customized layouts for your Substance articles. First let's learn how to install a theme:
Download the Substance Dark Theme. Extract the contents of the zip file. Now you need to locate the Substance Composer Application data directory on your system.
OS X~/Library/Application Support/Substance Composer
Windows%APPDATA%\Substance Composer
Now move the extracted folder (substance-dark) into the templates directory. Restart the Substance Composer and you should be able to select the Substance Dark Theme in the Publish Tab.
Publish Dialogue after selecting a custom theme.

Theme development

Themes are actually pretty simple and can be compared to Wordpress Templates. If you look at the contents of the Substance Dark Theme, you find a nodes folder, which has the HTML markup for all different content types. Main entry point is the document.html file. Under assets you can put anything you need to reference in your template, such as icon-images or stylesheet files. When referencing assets, not that you do not need to prefix /assets/ in your HTML, as the files will be copied to a flat structure.
Here's an example implementation of figure.html.
<div id="<%= %>" class="content-node figure">
  <div class="content">
      <img src="<%= node.image %>">
    <% if (node.caption) { %>
    <div class="caption"><%= annotated([node.caption, 'content']) %></div>
    <% } %>
The corresponding style sheet rules could look like this.
.content-node.figure { margin-bottom: 2em; background:#121415; }

.content-node.figure .content { max-width: 1000px; margin: 0px auto; text-align: center; }

.content-node.figure .content a { text-align: center; }

.content-node.figure .caption { font-size: 14px; color: #a9c5c5; margin: 0 auto; }

.content-node.figure img { max-width: 100%; }
However, you can do anything you want with regards to markup structure and CSS, there's are no rules you need to follow. You can also exclude information you don't need in your final publication. E.g. the list of authors. Feel free to build on the existing Substance themes to create your own.
Given the power of custom theming, Substance Composer is a great tool for web designers, who can enter the contents of a page, and easily generate HTML+CSS, based on their custom templates. Think of it like Jekyll, but with a visual front-end for content input. Also, when Jekyll is for multi-page blogs, Substance is for single-page web publications.

Known issues

In rare conditions there is the possibilty that the displayed content gets out of sync with your input. If Substance Composer exhibites this behavior, please first save your article using ⌘+S. Then, press ⌘+R to reload the interface. If you do encounter this issue and would like to detail the steps taken to reproduce it, please send a bug report to We'll try to address them as soon as possible.

Frequently Asked Questions


Why can't I publish with a single click?

Substance doesn't have a backend (yet). We chose to start with developing a system that doesn't require any infrastructure. That way we put the user in control of their content. We support all possible hosting options (SFTP, FTP, S3, Rackspace, etc.). We're planning to develop a platform for collaboration, but want to wait until the Substance document format is adopted well enough.

How can I publish a collection of documents?

Substance publications are self-contained and can live on its own. For us it was important to keep articles independent from their embedding context, as this allows maximum flexibility and compatibility. Of course you can embed Substance documents into your webpage. We'll tell you how in a series of tutorials that will be ready soon.

What's in an .SDF file?

.sdf files are just zip archives. You can rename them to .zip and extract its contents. Inside you'll find a content.json file plus assets like images.

How can I help make the Substance Composer better?

Use it extensively. Create and host publications. Tell us what you like and what could be improved. While Substance Composer can't cover all possible use cases we really value your feedback. We are also looking for partners that help us take development further and fund certain features that are highly requested. Please get in touch if you are interested in a collaboration.

Can I customize the output?

You can modify the CSS (style.css) and HTML (index.html) to add your desired style to a publication. Just be aware that your custom styles are overridden when you export an updated version to the same folder. Designers will soon be able to automate this process by creating templates for Substance Composer.
Centralised vs. Decentralised Publishing: How much freedom are we willing to pay for maximum convenience?
Modern and simple hosting service.
WinSCP is a free SFTP, SCP and FTP client for Windows.
Cyberduck is an FTP, SFTP, WebDAV, S3 & OpenStack Swift browser for Mac and Windows.
Substance Composer Webpage
Miro Video Converter
Jekyll is a blog-aware static site generator
Michael Aufreiter
Michael Aufreiter is the original creator of the Substance platform. He has constantly been working on the idea of creating a new user experience for document editing. In the past he has invented many popular web-technologies (eLife Lens,, Data.js, Github.js). 
Oliver Buchtala
Oliver Buchtala has joined the project in 2012 turning Substance from a platform into a flexible and extensible technology stack. He has worked over 15 years in software development.
This article was created with Substance, an open self-publishing system.