Skip to main content
Documentation Writing Content

Folder Structure

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

.
├── config # this is where frontend and server defaults are stored
├── frontend # this is where you put your CSS and JS for esbuild
│   ├── javascript
│   │   ├── index.js
│   │   └── widget.js
│   ├── styles
│   │   ├── index.css
│   └   └── layout.css
├── server # this is where you can (optionally) add API routes using Roda
├── src # this is where you put your resources and design templates
│   ├── _components
│   │   ├── footer.liquid
│   │   └── header.liquid
│   ├── _data
│   │   ├── members.yml
│   │   └── site_metadata.yml
│   ├── _layouts
│   │   ├── default.erb
│   │   └── post.serb
│   ├── _posts
│   │   ├── 2021-09-18-enjoying-the-celebration.md
│   │   └── 2022-04-07-checking-out-bridgetown-now.md
│   ├── images
│   │   └── logo.svg
│   ├── 404.html
│   ├── some_page.md
│   └── index.html # or index.md
├── output # this is the generated site after build process
├── plugins # this is where you can write custom plugins
├── bridgetown.config.yml # this is your Bridgetown configuration file
├── config.ru # Puma uses this to boot up the web server
├── esbuild.config.js # frontend bundler config
├── Gemfile
├── Rakefile
└── package.json

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

src/_components

A location for all your components which can be referenced by your layouts and resources to comprise a design system and facilitate template reuse. In Liquid, {% render "card" %} would insert the _components/card.liquid component. You can create Ruby components as well and save them here for use in Ruby layouts and resource files.

src/_data

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

src/_layouts

These are the templates that wrap resources 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 collections or folder paths).

src/_posts

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.

src/images

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 or relocate it under a parent assets folder.

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

Provided that the file has a front matter section, it will be transformed by Bridgetown as a resource. 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.

output

This is where the generated site will be placed once Bridgetown is done transforming all the content.

plugins

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.

server

This contains the base Roda appplication structure, used by Bridgetown to faciliate both the static files server and SSR/dynamic routes (if present).

.bridgetown-cache

.bridgetown-cache is used to improve performance over multiple builds by storing the results of expensive operations.

bridgetown.config.yml

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.

Gemfile

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

package.json

Manifest used by NPM to install frontend assets and set up commands you can run to compile your JavaScript, CSS, etc. via esbuild.

esbuild.config.js

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

Resources