Skip to content

Configuring the build

Jump to bottom
mbinyam edited this page Jun 19, 2019 · 11 revisions

Configuring the build

The build configuration is set in the config.yml file in the project's root directory. Additionally, build-specific configuration files can be added to the project root to override specific settings if needed.

Supported options are outlined below.

env

Description

Current build environment.

Default Value

development

theme

Description

Name of the current theme. Must map to a name of a directory in the themes directory.

Default Value

b-ber-theme-serif

src

Description

Name of the source directory.

Default Value

_project

dist

Description

Prefix for the name of the build directory. When building an EPUB, the output directory name will be project-epub.

Default Value

project

ibooks_specified_fonts

Description

The ibooks:specified-fonts option in the content.opf. Set this to true if you're including custom fonts.

Default Value

false

themes_directory

Description

Defines the themes directory for user-made themes.

Default Value

./themes

autoprefixer_options

Description

Defines the autoprefixer options to be used when parsing SCSS. See here for details.

Default Value

  browsers:
    - 'last 2 versions'
    - '> 2%'
  flexbox: no-2009

ignore

Description

Ignores files or folders. This is useful when used with build-specific configuration files for omitting unneeded assets.

Default Value

[]

base_url

Description

URL to map assets to during the web build.

Default Value

/

base_path

Description

Path that will be appended to the URL for the reader build.

Default Value

/

remote_url

Description

URL where the project is hosted for the reader build.

Default Value

http://localhost:4000/

reader_url

Description

URL where the remote reader build is located.

Default Value

http://localhost:4000/project-reader

bucket_url

Description

S3 bucket URL where the remote project is located. Used during the deploy task.

Default Value

null

private

Description

Injects a robots meta tag into the XHTML head elements during build with follow/nofollowandindex/noindex`.

Default Value

false

builds

Description

Download types to be linked to in the reader interface

Default Value

['epub', 'mobi', 'pdf']

epub | mobi | pdf | reader | sample | web

Description

Custom build specific configuration settings. Accepts all properties of the main configuration file.

Default Value

null

remote_javascripts

Description

Remotely hosted JavaScripts. URLs added here will be injected into the HTML before the closing body tag.

Default Value

null

remote_stylesheets

Description

Remotely hosted stylesheets. URLs added here will be injected into the HTML's head element.

Default Value

null

ui_options

Description

Defines UI display settings for header and footer navigation icons in the reader build. Object labels accept ##boolean values.

Default Value

navigation:
  header_icons:
    home: true
    toc : true
    downloads : true
    info: true
  footer_icons:
    page : true
    chapter : true

A sample configuration file is below that can be used as a template:

# ------------------------------------------------------------------------------
# Build Settings
# ------------------------------------------------------------------------------

# Minify and uglify scripts and stylesheets for production
env: development

# ------------------------------------------------------------------------------
# File System Settings
# ------------------------------------------------------------------------------

# Location of the source directory which contains all project assets
src: _project

# Output directory for the compiled project
dist: project

# Ignored files or folders
ignore:
  - _project/_fonts/
  - _project/_images/my-image.jpg

# Remotly hosted assets to be injected into builds
remote_javascripts:
  - https://my-analytics.js

remote_stylesheets:
  - https://my-remote-styles-1.css
  - https://my-remote-styles-2.css

# ------------------------------------------------------------------------------
# Display Settings
# ------------------------------------------------------------------------------

# Selected theme name. Show installed themes by running `bber theme list`
theme: serif

# Directory where user themes are stored
themes_directory: ./themes

# iBooks setting for enabling third-party fonts
ibooks_specified_fonts: false

# Autoprefixer. See complete list of options here: https://github.com/postcss/autoprefixer#options
autoprefixer_options:
  browsers:
    - 'last 2 versions'
    - '> 2%'
  flexbox: no-2009

# Show or hide various UI buttons for the reader build
ui_options:
  navigation:
    header_icons:
      home: true
      toc : true
      downloads : true
      info: true
    footer_icons:
      page : true
      chapter : true

# ------------------------------------------------------------------------------
# Deployment Settings
# ------------------------------------------------------------------------------

# Add a no-follow tag to the web build for private projects.
private: false

# Location of assets for the web build. This is necessary since the web build is
# a static website, and requires correct remote path names to load assets.
base_url: /demos/my-project

# Path that will be prepended to the URL when rendering the reader. This is
# useful for creating logical URL structures in an existing application, e.g.,
# on a website hosting projects, the `base_path` could be changed to `/project` so
# that all reader projects are served at `/project/my-project`.
base_path: /demos/my-project

# Location of the remotely hosted project.
remote_url: https://s3.amazonaws.com/my-bucket/my-object

# Location of the reader directory in the remotely hosted project.
reader_url: https://s3.amazonaws.com/my-bucket/my-object/project-reader

# Location of the S3 bucket where a build is hosted. This is used during the `bber deploy`.
bucket_url: s3://my-bucket/my-object
remote_url: https://example.com/

# URLs for remote downloads. These are available to download in the web and reader interfaces
builds:
  -
    url: https://s3.amazonaws.com/my-bucket/my-object/my-project.epub
    label: My Project (EPUB Version)
  -
    url: https://s3.amazonaws.com/my-bucket/my-object/my-project.pdf
    label: My Project (PDF Version)

b-ber

Getting started

Creating and authoring content

Publishing the project

Directives

Styling and theming

Misc

b-ber development

Clone this wiki locally