Configuring the build - triplecanopy/b-ber GitHub Wiki
Configuring the build
The build configuration is set in the config.yml
file in a project's root directory. Supported options are outlined below.
env
Description
The env
is the current build environment.
Default Value
development
theme
Description
The theme
is the name of the current theme, which must map to a name of a directory in the themes
directory.
Default Value
b-ber-theme-serif
src
Description
The src
is the name of the source directory.
Default Value
_project
dist
Description
The dist
is the prefix for the name of the build directory. When building an EPUB, the output directory name will be project-epub
.
Default Value
project
cache
Description
Define whether b-ber-reader should cache CSS in localStorage
.
Default Value
true
ibooks_specified_fonts
Description
The ibooks_specified_fonts
option allows for custom fonts to be set as the default in applications that support this feature in the content.opf
.
Default Value
false
themes_directory
Description
The themes_directory
defines the location of the themes directory for third-party themes.
Default Value
./themes
autoprefixer_options
Description
The autoprefixer_options
defines the Autoprefixer options to be used when parsing SCSS. More information can be found in the postcss Autoprefixer repository.
Default Value
browsers:
- 'last 2 versions'
- '> 2%'
flexbox: no-2009
ignore
Description
The ignore
provides an option to ignore specific files or folders, which can useful when used with build-specific configuration files for omitting unneeded assets.
Default Value
[]
base_url
Description
The base_url
is the URL to map assets to during the web
build.
Default Value
http://localhost:4000/
base_path
Description
The base_path
is the path that will be appended to the URL for the reader
build.
Default Value
/
remote_url
Description
The remote_url
is the URL where the project is hosted for the reader
build.
Default Value
http://localhost:4000/
reader_url
Description
The reader_url
is the URL where the remote reader
build is located.
Default Value
http://localhost:4000/project-reader
bucket_url
Description
The bucket_url
is the S3 bucket URL where the remote project is located, which is used during the deploy
task.
Default Value
null
private
Description
A robots
meta tag is added to the XHTML during web
and reader
builds. Setting this option to true
will set the this meta tags content to nofollow,noidex
.
Default Value
false
downloads
Description
The downloads
key defines the downloads that are available in the Reader's dropdown menu. The dropdown menu will be populated from the following keys in each entry in the downloads
array:
url
label
description
Default Value
[]
remote_javascripts
Description
The remote_javascripts
is the location of any remotely hosted JavaScript files. The URLs added here will be injected into the HTML before the closing body
tag.
Default Value
null
remote_stylesheets
Description
The remote_stylesheets
is the location of any remotely hosted stylesheets. The URLs added here will be injected into the HTML's head
element.
Default Value
null
ui_options
Description
The ui_options
define the UI display settings for header
and footer
navigation icons in the reader
build. The object labels accept boolean values.
Default Value
navigation:
header_icons:
home: true
toc : true
downloads : true
info: true
footer_icons:
page : true
chapter : true
group_footnotes
Description
The group_footnotes
option will control if the footnotes counter is reset for each chapter. Defaults to true
, which causes the footnote numbers to be reset for each chapter. Setting it to false
will not reset the counter on each chapter.
Default Value
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
# Cache assets for b-ber-reader
cache: true
# 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: b-ber-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
group_footnotes: 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
downloads:
-
url: https://s3.amazonaws.com/my-bucket/my-object/my-project.epub
label: My Project (EPUB Version)
description: Download the EPUB here
-
url: https://s3.amazonaws.com/my-bucket/my-object/my-project.pdf
label: My Project (PDF Version)
description: Download the PDF here