Using Ulysses and Vellum for High-quality eBooks

The Ulysses app can do a lot besides writing. I’ve written a lot about how I abuse the poor thing. Its export options offer a variety of formats. One that was convenient was the RTF option. It meant I had one click export to a standard rich text format that’s usually requested by publishers.

The v2.1 Ulysses update replaced RTF with DOCX, the new Word 2007 format. These files aren’t usually accepted via email because of the chance that they carry a macro virus. (Have you noticed all the email spam that includes an “invoice”? Yep, those files come contain a DOCX file pre-loaded with a macro virus!) Even so, I was a bit miffed when the Ulysses developers made me resort to another app to deal with the Ulysses export.

But I also found that there’s a couple of ways this also helped me out.

First off, I can send the output directly to Mac Pages for further formatting and conversion to PDF or ePub (occasionally I might even print something). No matter how good the Ulysses output styles are, there’s just some things have to be done in a app like Pages, Word, or InDesign. Fortunately both Pages and TextEdit can re-save the DOCX file in to the older Word ’97 DOC format. It’s not as universal as RTF, but it’s close enough and is usually accepted by most places.

But I have to admit the Ulysses developers did the right thing by keeping up with standards. One unexpected benefit is that the eBook creation app Vellum can receive Ulysses’ DOCX export and drop the contents directly into a formatted eBook without needing to save the Ulysses export to disk.
Directly exporting to Vellum from Ulysses. (Did you spot the countdown until this beta version expires?)

Well it doesn’t happen by magic, there’s a bit of planning involved.

Using Ulysses and Vellum together

First you need a style sheet that tells Ulysses to how to format the DOCX file. Vellum provides some sample Word templates that show the styles it uses to import a DOCX file. The actual text formatting is thrown out (the eReader handles that part) but the style names are what Vellum uses to figure out the book’s formatting.

This style sheet really needs nothing more than a mapping of Ulysses markup to a named DOCX style. In the Vellum Export style I created, I added some text formatting. This makes it easier to read in the preview window. Mostly it’s just using some centering and line spaces to separate elements.

The important part is that the markup elements map to the correct style names. For example heading-1 (aka h1 or #) maps to Vellum Chapter Title. This might seem obvious but there’s a few things going on behind the scenes. The assumption is that first level headings will be used as chapter titles. This means that to have the title of the book marked up properly it can’t use that heading. For Vellum’s purposes, it likes to have a section break between chapters. This also means the top level heading needs to include that too.

Ulysses export is also limited because of the number of tags it allows. While annoying when wanting to cover all the bases, it also prevents Ulysses from becoming overly complicated. But at the same time, there’s a need to get creative when mapping markup to DOCX styles.

Ulysses markup how-to

To make the best uses of the markup available, I had to use some headings in a unconventional way. This means the lesser headings (3, 4, 5, and 6) should not be used for page headings. They have their own special job to do.

Here’s how things map out.

Heading 1 (#) — Vellum Chapter Title

  • This is the basic heading that starts a new chapter.

Heading 2 (##) — Vellum Subheading

  • This is a subheading to break up a chapter into smaller chunks, and it won’t appear in the table of contents.

Heading 3 (###) — Vellum Attribution

  • This is the attribution line for a block quote. Use this on the line after one and Vellum will automatically format it with the leading dash.

Heading 4 (####) — Vellum Flush Left

  • This will place the text against the left margin regardless of the text indentation.

Heading 5 (#####) — Vellum Book Title

  • The text here will be loaded into Vellum’s book metadata page, and will be used for the name of the book when exporting.

Heading 6 (######) — Vellum Author

  • This will also load into the metadata page for the author’s name.

Block Quote (>) — Vellum Block Quote

  • Nothing changed here, use as you normally would.

Block Raw (~~) — Vellum Chapter Subtitle

  • Place a raw block after a Chapter Title and Vellum will load it into the chapter heading block as a subtitle.

Paragraph Divider (----) — Vellum Ornamental Break

  • Vellum will see this and insert a text doodad that you can style with its built in style picker.

To download the style sheet, you can find it on the Ulysses Style Exchange.


Here’s a short bit of Ulysses markup to show how the Vellum Export style works.
Text in Ulysses before exporting to Vellum.

The title page is nicely formatted with the correct information already inserted. I think it’s important to keep this info in Ulysses too, and not just add it after the import. I’d hate to mix up authors when doing multiple books.

Also, if there’s a book subtitle it needs to be added manually. There’s just not enough markup mappings to cover everything. But if you keep it as a comment below the book title, it’s ready to copy and paste.
Vellum title page.

Vellum automatically creates a formatted table of contents based on the styled headers. One less thing to worry about.
Vellum table of contents page.

The introduction is recognized by its title and is inserted into the book’s page hierarchy in the right place.
Vellum introduction page.

The first chapter pages show off all the automatic formatting done for us. Notice how everything came across and Vellum recognized it correctly.
Vellum chapter page with text.

Since the heavy lifting is done, there’s only a few loose ends to clean up. Like adding a copyright page, and any dedications or end matter you might want to include. In Vellum these are simple point-and-click operations. And shouldn’t take any time at all.

Next steps

If you’re ready to move on beyond Ulysses built in eBook export Vellum is the way to go. You can download a fully functional version version of Vellum and save your working files to disk, but you’ll have to pay before being able to save the completed eBook file. The prices are reasonable and start at $30 for one eBook (which include output to all the popular formats: iBooks, Kindle, Nook, Kobo, and aggregators like Smashwords and Draft2Digital).

With these two apps working side-by-side, it’s easy to separate the writing from the production and have a book done in no time. Remember to get the style sheet from the style exchange.

Also if you don’t want to bother with all this yourself, I can help! Contact me using the form below, and I can turn your text into a ready-to-upload eBook for a reasonable fee with quick turnaround.

2 thoughts on “Using Ulysses and Vellum for High-quality eBooks

  1. Thanks for this! I don’t meet a lot of writers who use Ulysses and Vellum together. I meet more Scrivener people to the point that I’m convinced they’re getting paid to praise Scrivener every chance they get lol (I have Scrivener, too – just not a fan of it compared to Ulysses, and now Vellum).

    I downloaded the Vellum theme and hope to use it for my next book once I’m done writing it in Ulysses. My problem is that I end up making the changes on Vellum because I’m already there and it kinda muddies the versions because Vellum doesn’t keep previous versions like Ulysses does.


    1. I do the same, even it’s a blog post. There’s always something that needs “improving.” I’m not sure there’s an easy way to solve this. I guess just make a rule to not edit in Vellum. 🙂

      Liked by 1 person

Comments are closed.