Chapter 8. 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 Chapter 9, 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.

Chapter 8. Required Fields

Chapter 8. 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"]
}

Chapter 8. Optional Fields

Chapter 8. theme

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

{
  "theme" : "oreillymedia/atlas_trade_theme"
}

Chapter 8. Formats

The formats objects holds all settings for the different formats. Here’s the basic skeleton. See Format Options for a list of options for the specific formats.

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

Chapter 8. Format Options

Chapter 8. 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.

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

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

Chapter 8. EPUB

• toc - see PDF
• index - see PDF
• epubcheck - set to true or false to toggle validation of EPUB against epubcheck and report results.

Chapter 8. MOBI

• toc - see PDF
• index - see PDF

Chapter 8. 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.
• 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.

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"
      ]
    }
  }
}