Styling and Theming

A theme is a collection of designs used to style every output format of a book. For example, a single theme would include designs for a PDF, an EPUB (the format for the iPad, Nook, etc.), a MOBI (the format for the Kindle), and an HTML website. Each of these designs would have a consistent look and feel, but with slight modifications to optimize the design for the output format. (Read more about styling each format in the following sections.)

All of the Atlas output formats (PDF, EPUB, MOBI, and HTML) are powered by CSS, the standard styling language for the Web. You can write an entirely new theme using CSS, that can be used for multiple projects, by multiple people, or you can just add CSS customizations for your specific project.


This documentation is not a comprehensive guide on how to write CSS, but rather how to set up CSS files to work with Atlas. For an overview of using CSS in publishing, see CSS Primer. Additionally, there are lots of resources online to get you started with learning CSS, and of course O'Reilly has many books on the subject.


Atlas uses themes to style projects. Each theme is built with CSS and split into 4 pieces, for each of the different output formats: PDF, EPUB, MOBI, and HTML. Atlas has two default themes built in: Trade and Technical. Feel free to use these themes as examples when creating your new design.

Creating a New Theme

Every new theme should include the following:

  • CSS to style the ebook and print PDFs
  • CSS to style the EPUB
  • CSS to style the MOBI (Kindle file format)
  • CSS to style an HTML website
  • An HTML file to add any extra header information or layout elements to the HTML website (optional)
  • Downloadable sample files for each format (optional)

Every theme should live in its own Atlas repository, and you can create this theme repository the same way you create a new project. Click the "New Project" button on the Projects page, give your repository a name, and then in the Templates section, click "Advanced" and choose "Theme". This will pre-populate your theme repository with all the necessary folders and blank CSS files for each format.


You can also create a public theme on GitHub for use in Atlas. 

Atlas expects themes to use a specific file structure, so if you aren't creating the theme via Atlas (as described above), then you'll need to make sure to set your theme up accordingly, as shown in the figure below.

Figure 8-1. The file structure for Atlas themes.

Styling for PDF Output

Atlas combines CSS with PDF processing software to create PDFs suitable for digital reading or professional printed books.


The specific PDF processing software we use is called Antenna House—you can read the documentation about Antenna House here.

Creating a PDF with CSS relies on the Paged Media module. For a primer on writing CSS for PDFs, see CSS Primer, read "Building Books with CSS 3" on A List Apart, or watch the presentation here.

Styling for EPUB Output (iPad, Nook, etc.)

Right now, the EPUB format is largely targeted at continuous, linear reading—creating more intricately-laid out files is fairly difficult, and getting these files to work on all the different eReading devices is even harder. There are a wide range of devices used to display EPUB files—the iPad, Sony Reader, and Nook, to name a few—and each of these devices offers a different level of support for CSS properties and selectors. Because of this, we advise you not to get too complex when styling for EPUB output. Here are a few CSS tips to get your EPUB files to display correctly, on all devices:

  • Keep all text in a single column
  • Don't rely on floats or absolute positioning
  • Page margins are off-limits on most devices
  • Not all devices render background colors or borders
  • Not all devices support less-common text styles (like text-transform)

It's a good idea to test your EPUB styles on all devices that you think your readers might use, if you can. The easiest way to test is simply to create an EPUB file using your CSS, and see how that file looks on each device.

Styling for MOBI Output (Kindle)

Designing for Kindle is very similar to designing for EPUB: most new Kindle devices can render CSS and HTML quite well—on the same level as EPUB readers. This means that you can generally use the same CSS styles for both your MOBI and EPUB formats.

However, there are still a lot of older Kindle devices in use (like the Kindle Keyboard). These devices have much more limited support for CSS styles, so it's generally a good idea to add an extra section of basic fallback styles for these devices, inside a media query, as shown in the following example.

 @media amzn-mobi {

  h1 {
    font-family: serif;
    font-size: 200%;

  h2 {
    font-family: serif;
    font-size: 150%;

  h3 {
    font-family: serif;
    font-size: 125%;

  h4 {
    font-family: serif;
    font-size: 120%;

If you don't want to add extra fallback styles for older Kindle devices, don't worry—we'll add some default styles for you if we don't see the media query in your mobi.css file.

Styling for HTML Output

Atlas comes with an option to export your project as a fully-functional website that you can upload to the server of your choice. When you build the project, you'll receive a zip of the project files, CSS, images, and any custom JavaScripts or other assets you've chosen to include, as discussed in Custom Javascripts.


To learn more about the different build options for exporting your project as a website, read the documentation here.

Writing CSS for HTML output is fairly straightforward—just style things as you would for the Web. We encourage you to consider including navigation elements, a header, and other standard website features to your HTML theme, so that the end result is a fully-functional, beautiful website.

The HTML layout file

In order to make a functional website, each file that you create in Atlas gets wrapped in a layout file that adds header information, links to JavaScripts and CSS files, and standard HTML wrapper tags. All Atlas projects will use a default layout.html file, but you can also create a custom layout file for your theme. For example, if you want to add a top navigation bar or extra navigation links before or after the book content.

If you choose to create your own layout file, simply create a file called layout.html and save it in the html folder in your theme repo alongside your html.css file. Your layout.html file must include some standard elements in order for it to work correctly with Atlas, but you can add any extra stuff in addition to those required elements.


Remember that anything you add to the layout.html file will appear on every page of your project website.

Here's the boilerplate stuff that needs to be in any layout.html file:

{{ doctype }}
<html lang="en" xmlns="">
    <meta charset="utf-8" />
    <title>{{ title }}</title>
    {{ header }}
  <body data-type="book">
    {{ content }}

You can see in the above code block that Atlas layout.html files use a mix of variables and HTML. Read up on variables in Includes. To see an example of a customized layout.html file, check out the Atlas Trade Theme.

Customizing Your Project Styles

Sometimes you don't need or want to create a whole new theme—you may want to keep most of the design the same, but have the text flow in 2 columns in the PDF instead of 1, or add a custom style for special boxes that you're adding to your book that aren't part of one of the available themes. By using our override architecture, you can customize your project design without needing to define styles for every single element.

Every Atlas project includes a theme folder where you can add custom CSS to override the theme styles or to create new styles for custom elements you want to add just to your project.

How to Do It

The Build system looks for CSS overrides in a theme folder within your project repository. The structure of the theme folder should look just like the structure of an actual theme:

Figure 8-2. File structure for theme overrides within a single project.

All of these files are optional—you only need to include them if you want to add custom styles or overrides for each format. You can also add a custom layout.html file just for your project if you're exporting it for the Web. Read about HTML layout files above (see The HTML layout file).

Advanced Styling for HTML Output

The HTML format offers more opportunity for interaction and styling than PDF and other ebook formats. When building for HTML output, you may specify other stylesheets in the atlas.json file as well as custom javascripts to be included in the head of every page. More documentation these settings can be found in the atlas.json HTML Format Section.

CSS Primer

This section includes all four parts of the CSS for Print screencast series by Nellie McKesson. Learn the basics of CSS and how to use it to design PDF output from Atlas.

Introduction to HTML and CSS

Basic Layout and Text Formatting

Paged Media Basics

Generated Content - Counters & Strings

Page and Line Breaks for PDF Output

Line breaks and page breaks for PDF output can be configured in two different fashions with Atlas.

Primarily, properties to define global rules on how line breaks and page breaks should be handled throughout the book can be set within the CSS theme. For example, designers can use the CSS hyphens property to define how hyphenation should be implemented across line breaks. Similarly, they can take advantage of CSS’s page-break properties, as well as its orphans and widows properties to set page breaking rules across the whole book (e.g., “Make sure there’s always a page break before a figure image and that there are at minimum two lines of a paragraph at the bottom and top of each page”).

Additionally, Atlas allows typesetters to calibrate individual page breaks on a case-by-case basis by adding corresponding markup attributes in the HTML (e.g., “Insert a hard page break right before Table 3-1”).

If you're using one of the default Atlas themes, or a theme that we've helped you create, you can force a PDF page break by applying one of the following classes to an element via the code editor:

  • class="pagebreak-before"
  • class="pagebreak-after"

If you're using a custom theme and would like help implementing this behavior, please contact us directly.