atlas.json

The Atlas build system uses a JSON file called 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 build, 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.

But if you're a more hands-on type, or if you're going to be building a lot via the API, then you can edit atlas.json manually, which makes it possible to change any of your build settings without ever using the UI. The atlas.json file is under version control in your GitHub repo, which means that you can have different settings per branch, or even build your book from any point in your Git history.

The following is a list of attributes you can use.

Required Fields

Files

The only required attribute is files, which 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", "subfolder/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

Use this to specify a theme to use when building the book. This must be the user/organization and project name of the repository. Lean more about themes.

{
  "theme" : "oreillymedia/atlas_trade_theme"
}
Note

If this field is omitted, Atlas will look only in the project's theme/ directory for style sheets.

Formats

The formats objects holds all settings for the different formats. Here's the basic skeleton. Following is a list of options for the specific formats.

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

PDF

  • toc - Set to true or false to toggle automatic generation of Table of Contents.
  • index - Set to true or false to toggle automatic generation of a book index.
  • version - Set to "web" or "print" to generate a PDF for print or digital reading.
  • syntaxhighlighting - Set to "false" to turn off syntax highlighting in the build output. Defaults to "true."
  • show_comments - Set to "true" to enable rendering of Atlas comments in build output.

Here's an example of what this could look like.

{
  "formats" : {
    "pdf" : {
      "toc" : true,
      "index" : false,
      "version" : "web"
      "syntaxhighlighting": false
      "show_comments" : false
    }
  }
}

EPUB

  • toc - See PDF.
  • index - See PDF.
  • epubcheck - Set to true or false to toggle validation of EPUB against epubcheck and report results.
  • syntaxhighlighting - See PDF.
  • show_comments - See PDF.

MOBI

  • toc - See PDF.
  • index - See PDF.
  • syntaxhighlighting - See PDF.
  • show_comments - See PDF.

HTML

  • toc - See PDF.
  • index - See PDF.

  • javascripts - An array of relative paths to javascript files to be inserted in the layout.html file. Files will be included in the HTML in the order in which they are listed.

    Note

    If you override the default layout.html and your project contains math content, you'll need to re-enable math rendering with the following:

    {
"javascripts": ["http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"]
}
  • stylesheets - An array of relative paths to CSS files to be inserted in the layout.html file which will override any theme CSS files. Files will be included in the HTML in the order in which they are listed.
  • syntaxhighlighting - See PDF.
  • show_comments - See PDF.

Here's an example of what this could look like.

{
  "formats" : {
    "html": {
      "index" : true,
      "javascripts" : [
        "libraries/jquery.js",
        "libraries/underscore.js",
        "custom_script.js"
      ],
      "stylesheets" : [
        "custom_styles.css"
      ]
    }
  }
}