Building Your Project

Video Walkthrough

If you are brand new to Atlas, watch this video for a complete walkthrough of how to build and customize your projects:


Before you build your project for the first time, you need to tell Atlas which files you'd like to build and which theme to use. Do this from the Configure tab.

Alt Text


Three text fields at the top of the Configure tab allow you to specify metadata for your project.

Metadata fields on the Configure tab

Text entered in the Title field will appear in the output for your project wherever the {{TITLE}} Liquid templating instruction has been placed in the source—for example, on the titlepage.html file included with new Book projects in Atlas. This field corresponds to the "title" field in an Atlas project's atlas.json file.

The Print ISBN-13 field should contain the unique identifier assigned to the print, rather than ebook, version of your project. If you do not know the ISBN for the print version of your project, feel free to leave this field blank. The correct ISBN for your project will be added to your project's metadata during production.

In the Language field, choose the primary language in which the book content is written. This will configure localizations for generated text in some O'Reilly stylesheets. For example, when using those stylesheets that support this feature, changing the Language to "French" will render the main heading on the Table of Contents as "Table des matières."

Files to Build

The Files section allows you to select which files should be included in your builds and determine their order.

Alt Text
Figure 7-3. Select which files to build.

On the left, you'll see a list of files in your project that are eligible to be built. Atlas only recognizes files with the following file extensions in this pane: .html, .xhtml, .xml, .md, .markdown, .asciidoc, and .asc.

The right-hand pane shows you the files Atlas will include when you build. You can move files from left to right by simply clicking on them in the Project Files pane, or remove them from your build list by clicking on the "X". You can also reorder the files in your build list by dragging and dropping them however you'd like.

If you created a new project with the book template, the build list will be automatically populated with the sample files that you see in the previous image.


Atlas themes are collections of CSS files that determine the styling of your output formats. Before you build for the first time, click the Change Theme button and select the theme that is most appropriate for your project.

Alt Text
Figure 7-4. Select a theme for your project.

If you created a new project with the book template, the Atlas Technical Theme will be selected automatically. You can learn more about themes and how to create your own custom styles here.

Output Formats

Atlas lets you build your project to four different output formats, depending on your needs and audience: PDF, EPUB, MOBI, and HTML.


The PDF format gives you a fixed-page rendering of your project. The content is split into static pages that will never change, much like a printed book. In fact, PDF is the file format that you'd use if you wanted to send your project to a professional printing press, in order to create printed books.

Atlas offers you the option to either create a print-ready PDF, or to create a PDF optimized for reading on the screen (many people still prefer to read ebooks in PDF format on their PCs). You can choose which type of PDF you'd like in the Build Settings.

Alt Text
Figure 7-5. The first two options in the Build Settings for the PDF format let you choose whether you want to create a PDF for print or for digital reading.


EPUB is the main file format used by devices like the iPad and Nook. Unlike a PDF, the EPUBs created by Atlas are reflowable--this means that users can change things like text sizes and margins, and the content will reflow across the "pages" of the device.

EPUB is a standard maintained by the International Digital Publishing Forum. In order to make it easier for device makers (like Apple) and content creators (like you) to build compatible products, the EPUB standard defines a number of rules about how the content should be encoded. Don't worry though: Atlas takes care of making your files completely valid and compliant, so all you need to worry about is creating something great.


Amazon has its own proprietary ebook format called MOBI, that is specifically designed to work with all Kindle devices and apps.


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 file of the project files, CSS, images, and any custom JavaScripts or other assets you’ve chosen to include.

Including Custom JavaScripts

You can include custom javascript files by hard-coding links into your layout.html file, or by adding them to your atlas.json file.

Shared Options

Table of Contents

All of the build formats offer the option to generate a table of contents based on your project chapter titles and headings. This saves you from having to manually update your table of contents every time the content gets restructured or a title changes. Atlas will build a table of contents for you, by automatically pulling together a nested list of all your chapter-level titles, as well as the first two levels of headings. 

There are two things you need to successfully generate a TOC:

  1. Enable TOC generation. You can do this under "Configure" for the format(s) you're trying to build, or directly in atlas.json as explained in the JSON docs.
  2. Add a <nav data-type="toc"/> placeholder tag in your content. This tag needs to be a root tag in your content—that means that it needs to be in a file, all on its own, and cannot be nested inside a chapter or in a <section> tag.


All of the build formats have the option to generate a back-of-the-book index. There are three things you need to successfully generate an index:

  1. Enable index generation. You can do this under "Configure" or directly in atlas.json as explained in the JSON docs.
  2. Add a <section data-type="index">&nbsp;</section> placeholder tag in your content. This tag needs to be a root tag in your content—that means that it needs to be in a file, all on its own, and cannot be nested inside a chapter or in another <section> tag.
  3. Go through your content and mark up the words you want in the index. This is a time-consuming process, but it's hard to automate. You can use our indexing tool in the visual editor to make the process easier. If you prefer to work in code view, then index entries, often called index tags, should be inserted as empty a tags, stating the level of the tag, as follows:
    <a data-type="indexterm" data-primary="ingredients" data-secondary="salt"></a>