Things I like
The first thing I noticed upon launch was the "Add Cover Image" link at the top, which shows me this is opinionated in terms of content hierarchy (which I'm fine with).
It was intuitively easy to create headings and sub-headings.
Content stored as JSON! w00t!
Using HTML markup for elements just makes sense.
Web publishing was easy.
The resulting web page is beautiful.
The table of contents on the right is really nice because it shows me my document outline at a glance.
Clicking on a heading in the table of contents and being taken there is very useful.
It's fantastic to have keyboard shortcuts for choosing a particular markup element (I mostly used the shortcuts for headings and lists).
Wow - having "remarks" and "errors" as an easy way to write comments on a part of the document is great.
It took me a while to discover it, and longer to understand what it was, but I like both the vertical scroll bar on the left as well as the blocks on it which communicate each "piece" of the document.
It looks like all parts are open source - w00t!
I can use html in the author attribute and link to my twitter account.
Images in the html output are not scaled down - at least the one I used wasn't. But it did appear at full original size - I'm not sure if there's a width limit to these or if its entirely encumbent upon the user to provide web-ready images?
It's nice to see the image resolution displayed on the bottom left of an inserted image.
Headings in the HTML output have anchor tags which show up on mouseover - nice!
HTML output means I can easily publish this document on my own server using ssh (and rsync for updates).
Things I don't like
Here are the things I don't like, found hard to use, a bug, unintuitive, or lack expected functionality.
Headings only support
h3. They should go all the way to
When creating a new heading, hitting tab twice to make it an
Apple + Ztwice to go back to the
h1, the Table of Contents correctly shows its an
h1, but the sizing in the document view still shows the smaller
h3size. I had to remove the heading style and add it back again to get the desired size showing.
The list items have a big bottom padding; it looks like each list item is a new list. They should be closer together.
The resulting html output from a list should use the html tags
<ul><li></li></ul>but instead it incorrectly uses
divs. This leads to vertically misaligned text at the start of the line between the first and second lines on multi-line list items.
Typographically, long lists in the published html are hard to read, for the above reasons.
Ordered lists can't be created, only unordered lists. There is a "numbering" option in the Publish tab, but this is only to do with headings in the document.
On inspecting the resulting content.json each list item shows up in the "nodes" array. That's surprising; I would have rather expected that each list item would be available in a "lists" array, like so:
Missing html elements
Ordered lists (as mentioned previously)
The Substance Composer app
The window cannot be dragged around in Mac OS 10.9 by clicking and holding on the menu bar, and then dragging to a new position. This is accomplished by dragging the sides of the app outwards to the new position.
This new window position isn't remembered when creating new documents or opening saved documents.
Occasionally when typing and the line wraps over to the next line, the document view doesn't scroll up so I can only see the top half of what I am writing (case in point: this sentence).
There is no "Open recent..." option in the File menu.
It's not obvious that the saved file will always be called "content.json" and therefore the more important thing is what folder the document gets saved in (the folder name becomes what I would normally think of as the document name). Yet when I open an existing file I must open the content.json file, not the containing folder.
There is no fullscreen view. This is a nice-to-have feature.
OS 10.9 suggests the correct spelling of a work when I mis-spell it in Textedit, but I don't have the option in Substance Composer (to be fair, I don't have that option in TextMate or TextWrangler either). It would be nice to have some kind of spell check/correction.
I had a case where the editing interface completely failed. I had 3 list items underneath an h1 heading, and another h1 heading after the list. With my cursor at the end of the last list item, I hit "enter" expecting to have another list item created. However, the cursor jumped to below the next heading. I couldn't create another list item. Yet when I went to the second list item and hit "enter" a new list item was created after the 3rd item. My guess is that the document thought the cursor was actually one line lower than it actually was. Closing and re-opening the document solved this error.
In typing the last sentence in the last paragraph my cursor got "confused" and nodejs crashed with this error message (I couldn't find any error message in the system log relating to this):
I had a similar cursor issue happening when cutting a heading and pasting it before another heading. My pasted heading appeared one paragraph lower than it should, and the heading in that paragraph appeared at my cursor position. To replicate, select the entire row a heading is in (i.e. place your cursor position at the start of the line, hold down the shift key and press the down key). The entire row is now selected (i.e. not just the text). Now, navigate to just before another heading in your document and hit Apple + V to paste. The pasted heading should incorrectly switch places with the lower heading.
The italics key only applies retroactively to highlighted text. I can't decide that I want this word to be italicised by first hitting Apple + I and typing my word. I have to highlight it after typing it and then hitting Apple + I.
I can't search within a document.
Closing and opening Substance Composer should re-open the last document worked on, or at least show a list of recent documents with the option to create a new document. It doesn't - it opens a blank document.
The keyboard shortcuts are only listed within the drop-down menu; they should show as tooltips when mousing over the Italics and Bold icons.
There is no standard Apple + O shortcut for opening a document.
Apple + X correctly cuts content, but I had one case where when pasting, the pasted content was "old" cut content. Repeating the procedure by re-cutting the content and pasting again didn't solve the issue. I had to choose Edit -> Cut from the menu.
When the cursor is on a completely different part of the document and I scroll elsewhere and click on an image, I get taken back to my cursor, which is odd, because there isn't any functionality which is accessible by clicking on an image.
When making changes and viewing the resulting html it would be nice to have a shortcut key to do this, especially in the editing stages of a document, as I found I published the document many times in a short space of time to test output. This means clicking the "Publish" tab, then "Export web page", then "Select" in the next dialog box.
When returning to the document editing view after publishing a web page, I'm taken to the top of the document. I rather want to return to my last cursor position.
The Substance Composer ecosystem
There is no explanation of how to use https://github.com/substance/converter with pandoc to convert the JSON to, say, markdown.
Is there a grunt task where I can use content.json as a source for, say, jekyll, so that I can write blog posts in Substance Composer and then convert them to markdown so that jekyll can do its thing?
If I want to insert Google Analytics code into the published html, do I have to write my own grunt/nodejs plugin to do this?
With consideration to the above question, is the publishing workflow extensible?
What I haven't tested
Video, audio, inserting an HTML file, subscript, superscript, remark, error, document sharing.
Copyright © 2014 Roger Saner
This article is distributed under the terms of the Creative Commons Attribution License, which permits unrestricted use and redistribution provided that the original author and source are credited. See Creative Commons Attribution License.
This article was created with Substance, an open self-publishing system.