Configuration Options

The tables below list the available settings for Bridgetown, and the various options (specified in the configuration file) and flags (specified on the command-line) that control them.

Global Configuration

Setting Options and Flags

Setting	Options and Flags
Site Source Change the directory where Bridgetown will read files Default: `src`	`source: DIR` `-s, --source DIR`
Site Destination Change the directory where Bridgetown will write files Default: `output`	`destination: DIR` `-d, --destination DIR`
Template Engine Change the template engine Bridgetown uses by default to process content files. Default: `liquid`	`template_engine: ENGINE (erb, slim, haml, etc.)`
Content Engine Change the content engine Bridgetown uses for its data pipeline. The resource-based engine will become standard for v1.0. Default: `legacy`	`content_engine: ENGINE (legacy, resource)`
Permalink Change the default permalink style or template used by pages & blog posts. Documentation here—and if you're using the Resource-based content engine, read this additional information.	`permalink: STYLE or TEMPLATE`
Slugify Mode Determine the method of transforming characters when slugs are generated. Info on available options here. Default: `pretty`	`slugify_mode: MODE`
Disable Disk Cache Disable caching of content to disk in order to skip creating a `.bridgetown-cache` or similar directory at the source to avoid interference with virtual environments and third-party directory watchers.	`disable_disk_cache: BOOL` `--disable-disk-cache`
Exclude Exclude directories and/or files from the conversion. These exclusions are relative to the site's source directory and cannot be outside the source directory.	`exclude: [DIR, FILE, ...]`
Include Force inclusion of directories and/or files in the conversion. `.htaccess` is a good example since dotfiles are excluded by default.	`include: [DIR, FILE, ...]`
Keep files When clobbering the site destination, keep the selected files. Useful for files that are not generated by bridgetown; e.g. files or assets that are generated by your build tool. The paths are relative to the `destination`.	`keep_files: [DIR, FILE, ...]`
Time Zone Set the time zone for site generation. This sets the `TZ` environment variable, which Ruby uses to handle time and date creation and manipulation. Any entry from the IANA Time Zone Database is valid, e.g. `America/New_York`. A list of all available values can be found here. When serving on a local machine, the default time zone is set by your operating system. But when served on a remote host/server, the default time zone depends on the server's setting or location.	`timezone: TIMEZONE`
Encoding Set the encoding of files by name (only available for Ruby 1.9 or later). The default value is `utf-8` starting in 2.0.0, and `nil` before 2.0.0, which will yield the Ruby default of `ASCII-8BIT`. Available encodings can be shown by the command `ruby -e 'puts Encoding::list.join("\n")'`.	`encoding: ENCODING`
Defaults Set defaults for front matter variables.	More Information Here

Site Source

Change the directory where Bridgetown will read files

Default: src

source: DIR

-s, --source DIR

Site Destination

Change the directory where Bridgetown will write files

Default: output

destination: DIR

-d, --destination DIR

Template Engine

Change the template engine Bridgetown uses by default to process content files.

Default: liquid

template_engine: ENGINE (erb, slim, haml, etc.)

Content Engine

Change the content engine Bridgetown uses for its data pipeline. The resource-based engine will become standard for v1.0.

Default: legacy

content_engine: ENGINE (legacy, resource)

Permalink

Change the default permalink style or template used by pages & blog posts. Documentation here—and if you're using the Resource-based content engine, read this additional information.

permalink: STYLE or TEMPLATE

Slugify Mode

Determine the method of transforming characters when slugs are generated. Info on available options here.

Default: pretty

slugify_mode: MODE

Disable Disk Cache

Disable caching of content to disk in order to skip creating a .bridgetown-cache or similar directory at the source to avoid interference with virtual environments and third-party directory watchers.

disable_disk_cache: BOOL

--disable-disk-cache

Exclude

Exclude directories and/or files from the conversion. These exclusions are relative to the site's source directory and cannot be outside the source directory.

exclude: [DIR, FILE, ...]

Include

Force inclusion of directories and/or files in the conversion. .htaccess is a good example since dotfiles are excluded by default.

include: [DIR, FILE, ...]

Keep files

When clobbering the site destination, keep the selected files. Useful for files that are not generated by bridgetown; e.g. files or assets that are generated by your build tool. The paths are relative to the destination.

keep_files: [DIR, FILE, ...]

Time Zone

Set the time zone for site generation. This sets the TZ environment variable, which Ruby uses to handle time and date creation and manipulation. Any entry from the IANA Time Zone Database is valid, e.g. America/New_York. A list of all available values can be found here. When serving on a local machine, the default time zone is set by your operating system. But when served on a remote host/server, the default time zone depends on the server's setting or location.

timezone: TIMEZONE

Encoding

Set the encoding of files by name (only available for Ruby 1.9 or later). The default value is utf-8 starting in 2.0.0, and nil before 2.0.0, which will yield the Ruby default of ASCII-8BIT. Available encodings can be shown by the command ruby -e 'puts Encoding::list.join("\n")'.

encoding: ENCODING

Defaults

Set defaults for front matter variables.

More Information Here

Build Command Options

Setting Options and Flags

Setting	Options and Flags
Regeneration Enable auto-regeneration of the site when files are modified.	`-w, --[no-]watch`
Configuration Specify config files instead of using `bridgetown.config.yml` automatically. Settings in later files override settings in earlier files.	`--config FILE1[,FILE2,...]`
Environment Use a specific environment value in the build.	`BRIDGETOWN_ENV=production`
Future Publish posts or collection documents with a future date.	`future: BOOL` `--future`
Unpublished Render posts that were marked as unpublished.	`unpublished: BOOL` `--unpublished`
Ruby Front Matter Process Ruby front matter (default true)	`ruby_in_front_matter: BOOL`
LSI Produce an index for related posts. Requires the classifier-reborn plugin.	`lsi: BOOL` `--lsi`
Limit Posts Limit the number of posts to parse and publish.	`limit_posts: NUM` `--limit_posts NUM`
Force polling Force watch to use polling.	`force_polling: BOOL` `--force_polling`
Verbose output Print verbose output.	`-V, --verbose`
Silence Output Silence the normal output from Bridgetown during a build	`-q, --quiet`
Liquid profiler Generate a Liquid rendering profile to help you identify performance bottlenecks.	`profile: BOOL` `--profile`
Strict Front Matter Cause a build to fail if there is a YAML syntax error in a page's front matter.	`strict_front_matter: BOOL` `--strict_front_matter`
Base Path Serve the website from the given base path.	`base_path: URL` `--base_path URL`

Regeneration

Enable auto-regeneration of the site when files are modified.

-w, --[no-]watch

Configuration

Specify config files instead of using bridgetown.config.yml automatically. Settings in later files override settings in earlier files.

--config FILE1[,FILE2,...]

Environment

Use a specific environment value in the build.

BRIDGETOWN_ENV=production

Future

Publish posts or collection documents with a future date.

future: BOOL

--future

Unpublished

Render posts that were marked as unpublished.

unpublished: BOOL

--unpublished

Ruby Front Matter

Process Ruby front matter (default true)

ruby_in_front_matter: BOOL

LSI

Produce an index for related posts. Requires the classifier-reborn plugin.

lsi: BOOL

--lsi

Limit Posts

Limit the number of posts to parse and publish.

limit_posts: NUM

--limit_posts NUM

Force polling

Force watch to use polling.

force_polling: BOOL

--force_polling

Verbose output

Print verbose output.

-V, --verbose

Silence Output

Silence the normal output from Bridgetown during a build

-q, --quiet

Liquid profiler

Generate a Liquid rendering profile to help you identify performance bottlenecks.

profile: BOOL

--profile

Strict Front Matter

Cause a build to fail if there is a YAML syntax error in a page's front matter.

strict_front_matter: BOOL

--strict_front_matter

Base Path

Serve the website from the given base path.

base_path: URL

--base_path URL

Serve Command Options

In addition to the options below, the serve sub-command can accept any of the options for the build sub-command, which are then applied to the site build which occurs right before your site is served.

Setting Options and Flags

Setting	Options and Flags
Local Server Port Listen on the given port.	`port: PORT` `--port PORT`
Local Server Hostname Listen at the given hostname.	`host: HOSTNAME` `--host HOSTNAME`
Live Reload Reload a page automatically on the browser when its content is edited.	`livereload: true` `-l, --livereload`
Detach Detach the server from the terminal.	`detach: BOOL` `-B, --detach`
Skips the initial site build Skips the initial site build which occurs before the server is started.	`--skip-initial-build`
X.509 (SSL) Private Key SSL Private Key, stored or symlinked in the site source.	`--ssl-key`
X.509 (SSL) Certificate SSL Public certificate, stored or symlinked in the site source.	`--ssl-cert`

Local Server Port

Listen on the given port.

port: PORT

--port PORT

Local Server Hostname

Listen at the given hostname.

host: HOSTNAME

--host HOSTNAME

Live Reload

Reload a page automatically on the browser when its content is edited.

livereload: true

-l, --livereload

Detach

Detach the server from the terminal.

detach: BOOL

-B, --detach

Skips the initial site build

Skips the initial site build which occurs before the server is started.

--skip-initial-build

X.509 (SSL) Private Key

SSL Private Key, stored or symlinked in the site source.

--ssl-key

X.509 (SSL) Certificate

SSL Public certificate, stored or symlinked in the site source.

--ssl-cert

Additional Configuration File Settings

Bridgetown runs with the following configuration options by default. Alternative settings for these options can be explicitly specified in the bridgetown.config.yml configuration file.

Note that if you change plugins_dir, the option is relative to the current working directory, not the content source folder (aka src). Other *_dir options are relative to the source folder.

# Where things are
plugins_dir         : plugins
collections_dir     : .
layouts_dir         : _layouts
data_dir            : _data
includes_dir        : _includes
collections:
  posts:
    output          : true

# Handling Reading
include             : [".htaccess", "_redirects", ".well-known"],
keep_files          : [".git", ".svn", "_bridgetown"]
encoding            : "utf-8"
markdown_ext        : "markdown,mkdown,mkdn,mkd,md"
strict_front_matter : false

# Filtering Content
limit_posts         : 0
future              : false
unpublished         : false

# Conversion
markdown            : kramdown
highlighter         : rouge
lsi                 : false
excerpt_separator   : "\n\n"

# Serving
detach              : false
port                : 4000
host                : 127.0.0.1
base_path           : "/"
show_dir_listing    : false

# System
timezone            : null # e.g. America/Los_Angeles
quiet               : false
verbose             : false
defaults            : []

liquid:
  error_mode        : warn
  strict_filters    : false
  strict_variables  : false

# Markdown Processor
kramdown:
  auto_ids          : true
  entity_output     : as_char
  toc_levels        : [1, 2, 3, 4, 5, 6]
  smart_quotes      : lsquo,rsquo,ldquo,rdquo
  input             : GFM
  hard_wrap         : false
  guess_lang        : true
  footnote_nr       : 1
  show_warnings     : false

Back to Configuration