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. The very fact that you “run a build” and not load up an application server to host and deploy your website is due to the fact that Bridgetown is a Jamstack web framework. This means the website your visitors will ultimately engage with is a “snapshot in time”—the product of a 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 (aka “shortcodes”). This is the point when you’d create blog posts, collection documents, etc. 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 documents are placed within layouts, Front Matter variables are made available to templates, any Liquid tags and filters are processed, formats like Markdown are converted to HTML, 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 switching on incremental build regeneration, but there are challenges with such approaches. Nevertheless, improving build time is a major goal of the Bridgetown core team as we look to the future.

The Webpack 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 yarn start or yarn deploy commands, essentially two build processes are kicked off: the Webpack build process and the Bridgetown build process. The two align when something magical happens.

  1. Webpack will conclude its build process by exporting a manifest.json file to the hidden .bridgetown-webpack folder. This manifest lists the exact, fingerprinted filenames of the compiled and bundled JS and CSS output files.
  2. Bridgetown, using the webpack_path Liquid tag, 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 (as long as you use the provided Yarn scripts!).

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.

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!

Next: Command Line Usage