Willamette Search ⌘K

Customizing Your Theme

There are a number of ways you can customize the Willamette theme after setup, from adjusting layouts to choosing new fonts, colors, and finishing touches like new shadows or borders.

Willamette also offers some configurable choices to pick different ways of presenting your content. These options are available either on a per-page basis via front matter or site-wide via an initializer config.

Let’s explore these customization options in detail.

Site-wide Options #

When calling init :willamette alone in your config, you get the default theme experience, but there are a few settings you can override via the initializer DSL. For example:

init :willamette do
  layout do
    grid_lines true
  end
end

The available settings are:

  • docs_url_segment (root URL of the Documentation collection, default is "docs")
  • bypass_style_guide (set to true to prevent the Style Guide from being published. You could also do this via a conditional, such as unless Bridgetown.env.development?)
  • layout ⤵️
    • grid_lines (set to true to display sidebars with the same background color as the main content, separated by borders)
    • code_dark (set to true to display code snippets with a dark theme even if the site in general is showing a light theme)

Blog Layout #

There are several available layouts and “post styles” to choose from for the blog page (normally at /blog though of course you can change that to /news or something else by renaming the src/blog.erb resource file).

The default is a single-column view showing plain text headlines (aka headline_only). If you’d rather display the posts in a grid layout (particularly applicable for the more advanced post styles), add a willamette variable and set the display_layout accordingly:

willamette:
  display_layout: grid

The available post style options besides headline_only are:

  • headline_with_summary
  • headline_with_image
  • headline_with_image_and_summary

Put it all together, your front matter might look like:

willamette:
  display_layout: grid
  post_style: headline_with_image_and_summary

The post summary is typically pulled from the first paragraph, but you can use the subtitle or description front matter variable which will be used for the summary. Read the blog post content documentation here.

Layouts & Classes #

The documentation, page, and post layouts in src/_layouts wrap content in an <article> tag.

You can add an article_classes string within a willamette front matter variable to add additional CSS class names, perhaps useful if you want to set up different styles for specific kinds of pages/posts.

The Bridgetown convention of looking for a page_class variable and adding that to <body> class names is also supported.

Design System Changes #

Willamette is designed so you can adjust various aspects of the theme’s design system via CSS Variables.

Between the variables provided by Willamette itself and those provided by the underlying Web Awesome framework, you have a lot of leeway in adjusting the design of your site and of various pages through CSS alone.

However, in some cases there’s no getting around it: you’ll need to override Willamette’s HTML markup directly.

Overriding Willamette’s HTML Markup #

Willamette tries to keep the bulk of the HTML markup under your control by storing the HTML in layouts & templates within your repo. For instance:

  • The header/navbar and sidebar component templates live in src/_components/shared
  • The footer template partial lives in src/_partials
  • Content-specific layouts live in src/_layouts
  • The blog archive lives in src/blog.erb

The “default” layout (which content-specific layouts render into) is contained within the Willamette gem, but you can copy that out to your repo by running the following commands:

bin/bt plugins cd Willamette/layouts
cp willamette/default.erb $BRIDGETOWN_SITE/src/_layouts
exit

This will update your default layout to include all of Willamette’s HTML markup rather than simply inheriting from it.

Specific Components #

Some of the features of various layouts/templates are provided by individual components within the Willamette theme. You can copy those out of the Ruby gem and then modify the component code & markup in your own repo. For example, to copy in the Willamette::PostMetadata component, run the following commands:

bin/bt plugins cd Willamette/components
mkdir -p $BRIDGETOWN_SITE/src/_components/willamette
cp willamette/post_metadata.* $BRIDGETOWN_SITE/src/_components/willamette
exit

You can review the various Willamette components here to get a sense of what you might be interested in modifying.

There’s a small chance pulling in Willamette components and modifying them could mean missing out on future improvements made in the theme when you upgrade your gem dependency. It’s recommended you try to make modifications via CSS first, and modify the HTML templates only if CSS proves insufficient.

Willamette sometimes contains additional markup and styles for components (and the <body> itself) within Declarative Shadow DOM (DSD) templates. This keeps the “light DOM” markup more streamlined. The DSD templates provided are:

  • holy_grail_layout.{rb,dsd.css}
  • header_navbar.{rb,dsd.css}

You can copy those files out just like the other components described above and then modify them within your repo.
Skip to content Close