Modifying Bootstrap in Sage

Sage uses the Bootstrap front-end framework by default, and that brings along a little baggage. Bootstrap on its own has a bit of a reputation – most of it good, but a couple of common complaints:

Bootstrap? Everyone uses Bootstrap and now the whole web looks the same!

Bootstrap looks great out of the box, and with the release of BS3, it looks even better. What is really meant here is that your site should really stand out visually to be noticed in the sea of Bootstrap.

Ugh, framework? No thanks, I’m always overriding styles, and it’s bloated.

For sure, Bootstrap may have a lot more CSS and JS included than if you built a site completely from scratch. The point is to have a base for the elements you need, but what about those you don’t need?

So what’s the deal…? Why start with Bootstrap?

That’s just it, we are starting with Bootstrap. And here is where it gets fun and saves you a lot of time: Bootstrap is a modular framework, built to help you quickly get a site up and running, and also quickly customize and configure styling and functionality.

So, here we will cover:

  1. Modifying your site’s entire theme from the assets/styles/common/_variables.less file
  2. Removing entire portions of the framework you are not using in the project (CSS & JS)
  3. Replacing Bootstrap with your CSS framework of choice

1. Using _variables.less to quickly customize a site

Unlike WordPress core, Bootstrap is designed to be modified for your needs.

The first file we will look at is the variables file from Bootstrap. This is where a large amount of the customization to Bootstrap’s existing styles takes place. Taking a look at this file will show you a long list of Less variables that are used throughout all the rest of the Bootstrap framework.

To override these changes, add your new variables to assets/styles/common/_variables.less. In one place you can customize the color of your site’s elements, the default spacing, fonts, etc. Make your changes to this file, run gulp, and the changes cascade through the whole site.

Take some time to review all the Bootstrap variables and understand how they work. Before writing any additional CSS for your site, make sure that the effect you are looking for cannot be easily achieved by overriding Bootstrap variables.

2. Removing unused components

Bootstrap is modular, and easily supports removing entire sections that you are not going to use in your project. To do this, we are going to edit the bower.json overrides for the Bootstrap package.

Less/CSS

By default, our main overrides for the Bootstrap package in bower.json only contains one file: ./less/bootstrap.less. This file imports all of the Bootstrap styles.

To remove Bootstrap components from our theme stylesheet, we need to replace the ./less/bootstrap.less override with a full list of the stylesheets we want to include.

As of Bootstrap 3.3.2, the full list of overrides would be:

    "bootstrap": {
      "main": [
        "./less/variables.less",
        "./less/mixins.less",
        "./less/normalize.less",
        "./less/print.less",
        "./less/glyphicons.less",
        "./less/scaffolding.less",
        "./less/type.less",
        "./less/code.less",
        "./less/grid.less",
        "./less/tables.less",
        "./less/forms.less",
        "./less/buttons.less",
        "./less/component-animations.less",
        "./less/dropdowns.less",
        "./less/button-groups.less",
        "./less/input-groups.less",
        "./less/navs.less",
        "./less/navbar.less",
        "./less/breadcrumbs.less",
        "./less/pagination.less",
        "./less/pager.less",
        "./less/labels.less",
        "./less/badges.less",
        "./less/jumbotron.less",
        "./less/thumbnails.less",
        "./less/alerts.less",
        "./less/progress-bars.less",
        "./less/media.less",
        "./less/list-group.less",
        "./less/panels.less",
        "./less/responsive-embed.less",
        "./less/wells.less",
        "./less/close.less",
        "./less/modals.less",
        "./less/tooltip.less",
        "./less/popovers.less",
        "./less/carousel.less",
        "./less/utilities.less",
        "./less/responsive-utilities.less",
        "./js/transition.js",
        "./js/alert.js",
        "./js/button.js",
        "./js/carousel.js",
        "./js/collapse.js",
        "./js/dropdown.js",
        "./js/modal.js",
        "./js/tooltip.js",
        "./js/popover.js",
        "./js/scrollspy.js",
        "./js/tab.js",
        "./js/affix.js",
        "./fonts/glyphicons-halflings-regular.eot",
        "./fonts/glyphicons-halflings-regular.svg",
        "./fonts/glyphicons-halflings-regular.ttf",
        "./fonts/glyphicons-halflings-regular.woff",
        "./fonts/glyphicons-halflings-regular.woff2"
      ]
    },

No tables in sight? Remove the "./less/tables.less", line.

JavaScript

Remove specific Bootstrap JavaScript components by removing the relevant file from the overrides list in bower.json.

Never going to use scrollspy? Remove the "./js/scrollspy.js" line.

3. Removing Bootstrap entirely

Bootstrap, like most everything else in Sage, is completely optional. The steps for removing all of Bootstrap would be:

  1. Edit bower.json and remove Bootstrap from the dependencies
  2. Edit the stylesheets in assets/styles/ to remove Bootstrap mixins
  3. Run gulp to re-compile your theme assets without Bootstrap
  4. Update any Bootstrap specific markup to match your new CSS, or alternative CSS framework

Now that Bootstrap is removed, you will need your own styling to apply to the default element classes, or replace classes throughout the template files to match another framework.

Read the discussion on our Discourse

Get our latest updates & occasional tips on building better WordPress sites

Follow @rootswp on Twitter