Skip to main content
Documentation Introduction

Core Concepts

It’s easy to get started with Bridgetown, but it helps to have a basic understanding of a few key aspects of the site build process so you know which tools to use for the right job. Websites using Bridgetown are built and deployed as atomic artifacts, but they can optionally provide dynamic routes via a secondary server process. This means the website your visitors will ultimately engage with was largely produced as a “snapshot in time”—the product of Bridgetown’s build process. How does that process work? Let’s find out!

The Build Process #

There’s a relatively linear process which occurs every time you run a build command:

  1. First, Bridgetown loads its internal Ruby APIs as well as any Ruby gems specified in the bridgetown-plugins group of your Gemfile.
  2. Next, Bridgetown looks for a configuration file in your current working directory and uses that to instantiate a site object.
  3. After loading the configuration, Bridgetown prepares the site object for loading the various types of content in your site repository, starting with custom plugins in the plugins folder.
  4. Plugins are then granted the ability to generate new content programmatically and define other features such as Liquid tags or Ruby helpers (aka “shortcodes”). This is the point when you’d create blog posts and other resources from data provided by an external API for example.
  5. Once plugins (if any) have loaded, Bridgetown starts systematically reading in files from the source folder (typically src):
  6. Once all of the data structures for the entire website are in place, Bridgetown renders all relevant content objects to prepare them for final output. This is when Front Matter variables are made available to templates, any Liquid or Ruby templates are processed, formats like Markdown are converted to HTML, resources are placed within layout templates, and generally everything is finalized in its proper output format (HTML, JSON, images, PDFs, etc.).
  7. The final step is to write everything to the destination folder (typically output). If all has gone well, that folder will contain a complete, fully-functioning website which can be deployed to any basic HTTP web server.

Normally during development, you will be running a local dev server, which means every time you change a file (update a blog post, edit a template, replace an image file, fix a bug in a custom plugin, etc.), that entire build process is run through again.

For small-to-medium sites and on reasonably modern hardware, this typically happens in only a few seconds or less. For really large sites with tens of thousands of pages, or if many external API calls are involved, build processes can slow down substantially. There are technical solutions to many of these slowdowns, which can range from caching API data between builds to limiting the number of files built in development. Improving build time is a major goal of the Bridgetown core team as we look to the future.

The Frontend Build Process #

There’s one aspect of the build process overlooked above: the compiling, compressing, and bundling of frontend assets like JavaScript, CSS, web fonts, and so forth.

When using Bridgetown’s built-in start or deploy commands, essentially two build processes are kicked off: the frontend build process (either esbuild or Webpack) and the Bridgetown build process. The two align when something magical happens.

  1. esbuild/Webpack will conclude its build process by exporting a manifest.json file to the hidden .bridgetown-cache folder. This manifest lists the exact, fingerprinted filenames of the compiled and bundled JS and CSS output files.
  2. Bridgetown, using the asset_path Liquid tag/Ruby helper, monitors that manifest, and whenever it detects a change it will regenerate the site to point to those bundled output files.
  3. This way, your website frontend and the HTML of your generated static site are always kept in sync.

Adding Extra Features to Your Site #

In addition to the work you do yourself to code, design, and publish your website, there are ways you can enhance your site by installing third-party plugins or applying automations. These may provide new features, themes, or software configurations in useful ways. Some examples:

You can discover links to these and many more in our Plugins directory.

Server-Side Rendering and Dynamic Routes #

For most content-rich websites intended for marketing, educational, or publishing purposes (blogs, etc.), a statically-built and deployed site may be all you need. But there may be times when you need a real backend running for your site, either to provide API endpoints your principal pages can communicate with via JavaScript, or to offer actual routes that are fully SSR’d.

Bridgetown provides a full SSR pipeline powered by the Roda web toolkit. Roda, like Rails or Sinatra, takes full advantage of Ruby’s Rack ecosystem and offers a minimalist yet elegant DSL for defining and handling routes via a “routing tree” as well as processing request/response cycles. Accepting form data or JSON payloads is a snap, and there’s even a core plugin you can configure to enable dynamic, file-based routing with all of Bridgetown’s template engines and component rendering at your disposal.

What to Learn Next #

There is detailed documentation available about each and every step mentioned above, so feel free to poke around and read up on the topics which interest you the most. And as always, if you get stuck or have follow-up questions, just hop in one of our community channels and a friendly Bridgetowner will endeavor to help you out!

Migrating from…?