Skip to main content
Documentation Configuration Customize Your Site

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

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, serbea, slim, haml, etc.)


Change the default permalink style or template used by pages & blog posts. Documentation here and 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



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, ...]


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, ...]

Additional Watch Paths

Supply additional directories not normally covered by Bridgetown or Zeitwerk's autoloader to the file watcher to trigger a rebuild/reload. The paths are relative to the site root (but you can also provide absolute paths).

additional_watch_paths: [DIR, DIR, ...]

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


Set the encoding of files by name. The default value is utf-8. Available encodings can be shown by the command ruby -e 'puts Encoding::list.join("\n")'.

encoding: ENCODING


Set defaults for front matter variables.

More Information Here

Destination folders are cleaned upon site builds

The contents of destination are automatically cleaned when the site is built. Files or folders that are not created by your site will be removed. If you need to retain certain files/folders, specify them within the keep_files configuration directive. (For instance, Bridgetown automatically keeps compiled frontend assets from esbuild/Webpack.)

Do not use an important location for destination instead, use it as a staging area and copy files from there to your web server.

Build Command Options #

Setting Options and Flags


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

-w, --[no-]watch


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

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


Use a specific environment value in the build.



Publish posts or collection documents with a future date.

future: BOOL



Render posts that were marked as unpublished.

unpublished: BOOL

-U, --unpublished

Ruby Front Matter

Process Ruby front matter (default true)

ruby_in_front_matter: BOOL

Force polling

Force watch to use polling.

force_polling: BOOL


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


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


Base Path

Serve the website from the given base path.

base_path: URL

--base_path URL

Do not use tabs in configuration files

This will either lead to parsing errors, or Bridgetown will revert to the default settings. Use spaces instead.

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
components_dir      : _components
islands_dir         : _islands
partials_dir        : _partials
cache_dir           : .bridgetown-cache
    output          : true
additional_watch_paths: []

# 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
future              : false
unpublished         : false

# Conversion
markdown            : kramdown
highlighter         : rouge

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

  error_mode        : warn
  strict_filters    : false
  strict_variables  : false

# Markdown Processor
  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
  include_extraction_tags: false
  mark_highlighting : true

Back to Customize Your Site