Making an eBook with Ulysses: a complete guide

I’ve been working on this article for a while. Ever since I started experimenting with ePubs exported from Ulysses, I’ve been blogging my results. Now I’m ready to share a full eBook production process using Ulysses and my KBasic style.

After introducing my KBasic style, I found that I still wanted to make some adjustments to it. Actually it was more than just a few adjustments. I tried the style on several eReaders and found that I needed to change the text markup too.

I’m not going to bury the lede on this one. The sample eBook I made for this article looks damn good.

Now with the update to KBasic it seemed like a good time to share the results of producing an eBook with Ulysses. I’ll be starting with the text of an article I wrote this spring. It’s a short memoir of my experience of traveling to Las Vegas to cover the Republican primary election this past March. I’m using it because it’s long enough to show the formatting across multiple chapters but not be too long for demonstration purposes. I hope you’d enjoy the story, but more importantly take away how simple formatting can create a good looking eBook.

I’ve uploaded a zip file that contains everything discussed in this article. It includes: the raw markdown formatted text I used for the final eBook.

cover.jpg: the artwork I made to use as a sample cover.

cover-internal.jpg: the reduced size cover for internal use.

KBasic.css: the CSS file contains the styling for the eBook.

KBasic.ulss: the KBasic style sheet ready for import into Ulysses. The Kindle file of the sample book.

OverUnder.epub: The ePub file of the sample book.

OverUnder-cover.epub: the ePub file that includes an interior cover.

The download link is at the end of this article.


The Ulysses app is great writing tool. But it’s the export options that make it shine. It can hold all your text and then export it to just about any other app. Everything is stored as markdown-formatted plain text. One of the most interesting export options is to the ePub file format. This is used by most eBook readers except for the Kindle.

Recent versions of Ulysses have improved the ePub output, and the eBooks produced pass ePub validation (important if you want to upload one to sell). There are several ePub styles included, but they seemed cluttered for my taste. I wanted something simple. The eReaders do a great job of presenting easy to read text. That’s their job. I wanted to work with that as the base and build up a style that that let the eReader do most of the work while still having the high-end formatting touches that people want.

The end result is KBasic v2.0.

KBasic style installation

Once you’ve downloaded and unzipped the zip file, simply double clicking on the KBasic.ulss file will open Ulysses and install the style sheet.

Or you can open Ulysses’ preference panel and click the Styles icon in the top right, then click Add Styles… in the bottom right. Then use file chooser to locate the KBasic.ulss file and click Add.

You should now see KBasic as a style option in the ePub export panel.

Book info

The text I used for this sample book is from an article I wrote for It’s a short memoir of my experience traveling to Las Vegas to cover the Republican primaries and the candidates appearing there called Overwhelmed and Undergeared. I made a few minor copyedits, but the main text is basically the same as what was published. The biggest changes were to the formatting. I broke up the body into chapters and subheadings so I could show how they looked with the KBasic style. I also added copyright, dedication, and introduction chapters to show how a full featured book might look.

The files you can download have been tested in iBooks (Mac), iBooks (iOS), Kindle (Mac), Kindle (iOS), Kindle Touch, Kindle Fire 7”, and Kindle Previewer 3 (Mac, beta).

I hope you enjoy the story, but more importantly I hope you can see the results you can get from a plain text file and Ulysses’ export functionality.

Document formatting

If you look at the file, you’ll see the raw text I used. This has been exported directly from Ulysses as markdown formatted plain text, and it shows how little formatting I had to do to get a nice looking eBook. The whole book is in one file, but it could live inside of Ulysses as several sheets, one chapter to each.

I’ll go through each section and discuss the formatting used.

Text in Ulysses before conversion to ePub.


The way eBook covers are handled depends on the reading platform. The external cover is the image you drop into the image box when exporting to ePub. It’s the one you see when in the grid view of your preferred eReader. There tends to be a lot of argument about which aspect ratios are best and what the pixel size should be. For this sample book, I’m using a cover I designed in Lightroom’s print module. I started with a page size of 12x18 inches (Tabloid Oversize, 1.5 aspect), and placed the three photo frames to hold the pictures of the candidates.

Page setup showing Tabloid Oversize selected.

Then I used the File Resolution option to set the pixel size. In this case 150 ppi, which give a final resolution of 1800x2700. This is a touch smaller than the recommended sizes, but I wanted to keep the file size down for this sample. A ppi of 300 would yield a finished size of 3600x5400 and be large enough even for a coffee-table sized print book.

Page layout in Lightroom ready for pictures to be dragged into place.

Once it was “printed” to a JPEG file, I opened it in Mac Preview to add the title text. It’s a simple cover for demonstration purposes, and I was able to pull it together quickly.

Finished cover after text was added in Mac Preview.

This is the file that gets dropped into the cover box when exporting from Ulysses.

Internal cover

The interior cover is something completely different from the “exterior” cover we just discussed. An interior cover exists when the cover is duplicated and becomes the first page of the eBook. Kindles use both internal and external covers by default. I guess this is so that we can look at the cover without having to close the book and go back to the grid view on the eReader’s home screen. The kindlegen app provided by Amazon does this automatically, and requires nothing more than to have the external cover in place before the conversion happens.

For every eReader other than Kindle the interior cover is optional. If you want one, it has to be added as a image inline with the text. Some books don’t have this, but I’m seeing more than do. It’s a simple matter, only requiring a couple of extra steps.

The first is to reduce the file size so that the ePub file stays a reasonable size. I simply duplicated the cover image and renamed it to cover-internal.jpg. Then in Preview and I resized it to 800x1200 reducing the size from 1.9MB to 231KB, or just over 1/10th of the original size.

Reducing the size of the cover file to use as an interior cover.

This image will be on the very first line of our sheet in Ulysses where it will create the internal cover.

Ulysses markdown showing the interior cover image in place.

The easiest way to handle this in Ulysses is to have the cover image on a separate sheet and export twice. Once with that sheet included, which will make your default .epub file for iBooks. Then once without, and use the second export to run through kindlegen. The second .epub can be trashed after the conversion is complete and you have your .mobi file.

If this seems like too much trouble you can leave it out. It’s strictly personal preference.

Title page

For the sample book the title page includes three elements. The first is the the title, then the optional subtitle which is followed by the author’s name.

Ulysses markdown showing the title page.

The markdown I used is:

     # Overwhelmed and Undergeared

 ##### _Two Days on the Campaign Trail in Nevada_

###### by

       Jennifer Mack

The title has the heading-1 tag (#) which is also used for chapter titles, but it gets a little extra styling. The subtitle uses the heading-5 tag (#####) which is smaller but bold and centered. It also add a touch of spacing to keep the title page from getting too crowded. The original KBasic relied on the CSS to style the subtitle without needing header tags. But as I experimented with different eReaders, it just didn’t work well. So I went back to the more reliable way of manually tagging the elements.

The author’s name is tagged with header-6 (######) and is simply centered on the page page. If you prefer to have the author’s name larger, header-3 (###) is an option. If you’d like to have “by” above the name, don’t make a new paragraph. Use shift-return to create a soft break and have all the text be formatted the same. If you select the text you can see the “bent arrow” () of a soft break instead of the “pilcrow” () of a hard break.

That’s all it takes to make a title page. Best part is that it gets even easier from here.

Front matter

This is another change from the first versions of KBasic where CSS selectors were causing problems. I’ve found it’s easier to use an inline comment (++) rather than CSS to make the chapter title disappear. When the heading text is commented out, the header won’t show up in the book. But it will be used in the HTML title element. The title element is what gets indexed into the table of contents drop down. So there’s no distracting title on the page, but the ToC works as it normally would. If it’s a bug, I hope the Ulysses developers don’t fix it. It’s a perfect solution.

Ulysses markdown showing the copyright and dedication pages.

One thing to remember is to add a non-breaking space (option-space) after the closing comment tag. This way the space at the top of the page is preserved. Also, the stylesheet doesn’t add any italics. If you want italics, add it using character styles in the text.

Copyright & Dedication page

These pages are almost identical except for the amount of text. The copyright page makes use of a horizontal line to separate elements. The text is centered on the dedication page by using header-4 (####). The italics are added to the text.

Markdown from the copyright page:

# ++Copyright++ 

Copyright © 2016 by Jennifer Mack


All rights reserved.

No part of this book may be reproduced in any form or by any electronic or mechanical means, including information storage and retrieval systems, without written permission from the author, except for the use of brief quotations in a book review.

Markdown from the dedication page:

   # ++Dedication++ 

#### _To all those struggling with eBook formatting. You have my sympathy.


This is simple a chapter that starts with a header-1 and has several header-2 subheadings. There’s no special formatting needed, and this is where your prose shines.

Ulysses markdown showing the introduction page.

I’ve used all the main markdown elements in the introduction so they’d be in the eBook as a live demonstration of the KBasic style.

Main chapters

The following chapters (The Beginning, The Trip, Donald Trump, Marco Rubio, Ben Carson, and Afterword) are to show how the style looks over longer passages of text. There’s very little formatting here, and the eReaders do their job of presenting text in a extremely legible fashion. They all start with header-1 with no other formatting needed.

Ulysses markdown showing the first chapter.

Block quotes

The block quote at the beginning of the Trump chapter requires nothing more than two or more block quote paragraphs together (>). The text will be inset from the margins and italicized. The last one will be the attribution line, and will be offset to the right and have the em dash () automatically inserted. You can see in the text, there’s no special formatting needed.

Ulysses markdown showing a block quote with attribution line.

The Afterword chapter contains an unordered list. It uses the default formatting for whichever eReader you’re using.


I’ve made slideshows of the sample eBook on a few readers. These show exactly how the style sheet is interpreted and how little formatting you actually need.

iBooks (Mac)

This with the internal cover image.

Kindle (Mac)

Kindle Touch

These are genuine screenshots. To get them hold the Touch’s home button for three seconds then tap the screen.

I was surprised at how well this old Kindle handled the latest CSS formatting. I didn’t expect the block quote to style correctly as the guide published by Amazon said the CSS selectors I used were not supported.

Kindle Fire 7”

iBooks & Kindle (iPhone 5)

The books work as expected, except the block quote style doesn’t get applied to the attribution line.


I didn’t include any images in the sample book, mainly to keep the file size down. They do get their own minimal styling treatment.

On my iPhone 5, the title ran over the right edge a bit. I think that was mainly because KBasic turns off hyphenation, and the words were just too long to fit properly. I’m letting that go, since it seems to be an edge case.

I didn’t include any images in the sample book, mainly to keep the file size down. They do get their own minimal styling treatment to be centered and have italic captions.

Right now the only place to get KBasic 2.0 is right here. It’s included in the zip file with the samples from this article. I have a version posted on the Ulysses style exchange, but there’s no way to update a style. I haven’t decided if I’ll delete that version or create another entry for 2.0.

Download Link: KBasic 2.0


If you’re a high-volume Kindle reader, you’ve probably noticed that a lot of self-published books have crappy formatting. There’s a lot of ways to convert your text to an eBook. But only a few that really look good. The one common denominator seems to be too much styling—not too little. That’s why I started from the default style and built it up from there. The eReaders are designed to give a good reading experience out of the box. There’s only so much you can do before you start messing that up. I hope this article showed you how good a eBook can look when you dial the styling down a notch.

Now all of you Ulysses users out there can make beautiful eBooks with minimal effort too. The .zip file includes the Kbasic.ulss file ready to install. As always the hard part is doing the writing in the first place. But now producing your own eBooks is probably the easiest part.

If you’d like help getting your eBook together, use the form below to contact me and we can work together to get your book out into the world quickly and for less money than you think.

Just check the box (or boxes) for the area you’d like to ask about and I’ll get back to you within a day or so.

[contact-form][contact-field label=“Email” type=“email” required=“1” /][contact-field label=“Ebook production” type=“checkbox” /][contact-field label=“Editing” type=“checkbox” /][contact-field label=“Cover design” type=“checkbox” /][/contact-form]