Project Options

Configure

Before you build your project for the first time, you need to choose output settings. Do this from the Configure tab.

Metadata

Three fields at the top of the Configure tab allow you to specify metadata for your project, which is used in the production of ebooks.

Files to Build

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

The Files list and the Build Contents list

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

The right-hand Build Contents pane shows you the files Atlas will include when you build. You can drag files from left to right by clicking on them in the Project Files pane or remove them from your build list by clicking on the "⊖" icon. You can also reorder the files in your build list by dragging and dropping them however you’d like. When you’re done, click the "Save Settings" button below the Build Contents pane.

Theme

Atlas themes are collections of CSS and XSL files that determine the styling of your output formats.

Generic "Trade" and "Technical" themes are provided as a default in the Themes section. O’Reilly editorial or production staff can provide paths to custom themes for O’Reilly book series.

Output Formats

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

PDF

The PDF format is a fixed-layout rendering of your project. The content is split into static pages that do not change with the viewscreen, as in a printed book.

Atlas offers you the option to either create a print-ready PDF, or to create a web PDF optimized for reading on the screen. O’Reilly sends the Print version PDF to printers when a project has finished production. You can choose which type of PDF you’d like in the PDF Settings tab.

EPUB

EPUB is the main file format used by e-reader devices as well as the O’Reilly Learning Platform. 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 W3C Publishing Working Group. In order to make it easier for device makers (like Apple) and publishers (like O’Reilly) to build compatible products, the EPUB standard defines a number of rules about how the content should be encoded. All O’Reilly EPUB products are compliant with the EPUB standard.

MOBI

Amazon’s Kindle devices and apps have their own proprietary ebook format, called MOBI. Amazon now creates their MOBIs in-house from EPUBs, so this build option is deprecated.

HTML

When you build HTML for a project, you’ll be able to download a zip file of the project files, CSS, and /images. This can be useful for debugging or saving the project files locally.

Options for All Formats

Each build format offers 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 steps to successfully generating a TOC:

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 section.
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. Usually, this file is called toc.html.

Index

Each build format supports the option to generate a back-of-the-book index. There are three steps to successfully generating an index:

Enable index generation. You can do this under "Configure".
Add a <section data-type="index"/> 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. Usually, this file is called ix.html.
Add index tags where appropriate in the content. This is done by a professional indexer during the production phase of an O’Reilly book project.

atlas.json

The Atlas build system uses a JSON file named atlas.json to save build settings for a particular project. This file lives in the root of each project and is required to trigger a successful build.

If this sounds scary to you, don’t worry: Atlas will create this file for you the first time you visit the Configure page, and will write to this file every time you change your build settings in the UI, so you don’t ever have to look at this file if you don’t want to.

If you’re a more hands-on type, you can edit atlas.json manually, making it possible to change any of your build settings without ever using the UI. The atlas.json file is under version control in your repo, which means that you can have different settings for different branches.

The following sections describe the attributes that can be defined in atlas.json.

Files

files is an array listing the files to build in the order you’d like them sequenced in your book. All of these files need to exist in the repository and should be referenced with relative paths from the atlas.json file.

{
  "files" : [
    "chapter1.html",
    "chapter2.html"
  ]
}

Optional Fields

Branch

This field specifies the name of the project branch from which to build.

{
  "branch": "master"
}

Title

Specifies the title of output files.

{
  "title": "Your title here"
}

Theme

Specifies a theme to use when building the book. Each O’Reilly book series has its own custom theme.

{
  "theme" : "oreillymedia/animal_theme_sass"
}

Formats

The formats objects holds all settings for the different formats. Here’s the basic skeleton. The following sections list the options for the specific formats.

{
  "formats" : {
    "pdf" : {
      "option" : "value"
    }
  }
}

PDF

toc: Set to true or false to toggle automatic generation of Table of Contents. This will be true for nearly all O’Reilly projects.
index: Set to true or false to toggle automatic generation of a book index. This will generally be true for books and false for other project types.
version: Set to "print" or "web" to generate a PDF for print or digital reading, respectively. In O’Reilly themes, the print PDF will have trim lines and will display URLs in parentheses following the text to which they’re anchored.
syntaxhighlighting: Set to false to suppress syntax highlighting in the build output. This is usually set to true. Note that syntax highlighting will be suppressed in the print PDF output for grayscale projects.
show_comments: Set to true to enable rendering of Atlas comments in build output.
trim_size: Sets the trim size for the book. This will almost always be "7inx9.1875in" or "6x9in". The O’Reilly production staff will set this value based on the specifications for each project.
antennahouse_version: Sets the version of AntennaHouse (the software Atlas used to build the PDF). Adjusting this value can sometimes resolve failing builds. O’Reilly production staff can choose an appropriate version for a project.

Here’s an example configuration for PDF builds:

    "pdf": {
      "version": "print",
      "color_count": "1",
      "index": true,
      "toc": true,
      "syntaxhighlighting": true,
      "show_comments": false,
      "trim_size": "7inx9.1875in",
      "antennahouse_version": "AHFormatterV62_64-MR4"
    }

EPUB

toc: See the description in PDF above.
index: See PDF.
epubcheck: Set to true or false to toggle validation of EPUB against EPUBCheck and report results. This should be set to true at all times in order to ensure that the EPUB meets the required quality standards.
syntaxhighlighting: See PDF.
show_comments: See PDF.
downsample_/images: Set to true to automatically reduce the resolution of /images in the EPUB. This is useful for reducing the overall file size of EPUBs containing large /images. Unless production staff is made aware of a problem with file size in distribution, they will set this value to false.
mathmlreplacement: Set to true to have Atlas represent equations written in LaTeX with PNG /images of the equations. If this attribute is set to false, EPUBs will represent equations written in LaTeX with MathML, which is inconsistently supported across EPUB readers. For the sake of improved appearance and accessibility on the O’Reilly learning platform, O’Reilly’s production staff will set this attribute to false.

MOBI

This option is now deprecated. See the MOBI section.

HTML

toc: See PDF.
index: See PDF.
syntaxhighlighting: See PDF.
show_comments: See PDF.

Project Options

Configure

Metadata

Files to Build

Theme

Output Formats

PDF

EPUB

MOBI

HTML

Options for All Formats

Table of Contents

Index

atlas.json

Files

Optional Fields

Branch

Title

Theme

Formats

PDF

EPUB

MOBI

HTML