Rubyists Assemble! We're currently raising funds to help drive the launch of 1.0! Join the effort today ▸

Folder Structure

The typical folder structure for a Bridgetown site usually looks something like this:

├── frontend # this is where you put your CSS and JS for Webpack
│   ├── javascript
│   │   ├── index.js
│   │   └── widget.js
│   ├── styles
│   │   ├── index.scss
│   └   └── layout.scss
├── src # this is where you put your content and design templates
│   ├── _components
│   │   ├── footer.liquid
│   │   └── header.liquid
│   ├── _data
│   │   ├── members.yml
│   │   └── site_metadata.yml
│   ├── _layouts
│   │   ├── default.html
│   │   └── post.html
│   ├── _posts
│   │   ├──
│   │   └──
│   ├── images
│   │   └── logo.svg
│   ├── 404.html
│   ├──
│   └── index.html # or
├── output # this is the generated site published via bridgetown build/serve
├── plugins # this is where you can write custom plugins
├── bridgetown.config.yml # this is your Bridgetown configuration file
├── Gemfile
├── package.json
└── webpack.config.js

The location of pages in your source folder structure will by default be mirrored in your output folder, whereas posts are handled in a special way. You can customize these permalinks via front matter and global configuration options.

Overview of Files & Folders

File / Directory Description


Liquid components (aka partials) which can be referenced by your layouts, posts, and pages to comprise a design system and facilitate template reuse. The tag {% render "card" %} would insert the _components/card.liquid component.


A place for well-formatted structured data. Bridgetown will autoload these files and they will then be accessible via For example, given members.yml, you can access the contents of that file via Supported formats are: .yml/.yaml, .json, .csv, and .tsv.


These are the templates that wrap posts, pages, and even other layouts. Layouts are chosen on a file-by-file basis via the front matter (and you can configure default layouts for different document types or folder paths). The Liquid tag {{ content }} is used to inject page content into the layout template.


This is where you add dynamic blog-style content. The naming convention of these files is important, and must follow the format: YEAR-MONTH-DAY-post-title.EXT (aka .md, .html, etc.). The permalink can be customized for each post. Posts are a built-in collection, and you can configure other collections in addition to (or even instead of) posts.


You can save images here and reference them in both your markup and CSS (e.g. /images/logo.svg). The name of the images folder is completely arbitrary…feel free to rename it, relocate it under a parent `assets` folder, or however you'd like to set things up.

src/index.html or src/ and other HTML, Markdown, etc. pages

Provided that the file has a front matter section, it will be transformed by Bridgetown. You can create subfolders (and subfolders of subfolders) to organize your pages. You can also locate pages within _pages to line up with _posts, _data, etc.

General files/folders in the source folder

Every other directory and file except for those listed above—such as downloadable files, favicon.ico, robots.txt, and so forth—will be copied verbatim to the generated site as Static Files.


This is where you'll write custom plugins for your site to use. (Third-party plugins are installed as Gems via Bundler.) Typically there will be one site_builder.rb superclass, and you will add new builder subclasses to the plugins/builders folder. Read all about it in the Plugins documentation.


This is where the generated site will be placed once Bridgetown is done transforming it. It’s a good idea to add this to your .gitignore file.


.bridgetown-metadata helps Bridgetown keep track of which files have not been modified since the site was last built and which files will need to be regenerated on the next build. .bridgetown-cache is used to improve performance over multiple builds. It’s a good idea to add these to your .gitignore file.


Stores configuration data. A few of these options can be specified from the command line executable but it’s generally preferable to save them here.


Used by Bundler to install the relevant Ruby gems for your Bridgetown site.


Manifest used by Yarn to install frontend assets and set up commands you can run to compile your JavaScript, CSS, etc. via Webpack—as well as perform other tasks. Typically there are a couple scripts that are used to load the live-reload Browsersync server and run the Bridgetown and Webpack watchers simultaneously.


Configuration file used by Webpack to compile frontend assets and save them to the output folder alongside your Bridgetown content.

Next: Themes