1. Documentation
  2. 8.x-3.x
  3. Sub-Theming.md
  4. Sub-Theming

topic Sub-Theming

If you haven't already installed the Drupal Bootstrap theme, read the Getting Started topic. Below are instructions on how to create a Drupal Bootstrap based sub-theme. There are several different variations on how to accomplish this task, but this topic will focus on the two primarily and most common ways.

You should never modify any theme or sub-theme that is packaged and released from Drupal.org, such as Drupal Bootstrap. If you do, all changes you have made will be lost once that theme is updated. Instead, you should create a sub-theme from one of the provided starterkits (this is considered a best practice). Once you've done that, you can override CSS, templates, and theme processing.

Using the Starterkit

The starterkit provided by this base-theme supplies the basic file structure on how to construct a proper Bootstrap based sub-theme for use with a CDN Provider (like jsDelivr) or for use with compiling Bootstrap Framework source files.

NOTE: Using a CDN Provider is the preferred method for loading the Bootstrap Framework CSS and JS on simpler sites that do not use a site-wide CDN. There are advantages and disadvantages to using a CDN Provider and you will need to weigh the benefits based on your site's own requirements. Using a CDN Provider does mean that it depends on a third-party service. There is no obligation or commitment made by this project or these third-party services that guarantees up-time or quality of service. If you need to customize Bootstrap, you must compile the Bootstrap Framework source code locally and disable the cdn_provider theme setting.

WARNING: All locally compiled versions of Bootstrap will be superseded by any enabled CDN Provider; do not use both.

  1. Copy ./themes/bootstrap/starterkits/THEMENAME to ./themes.
    • Rename the THEMENAME directory to a unique machine readable name. This is your sub-theme's "machine name". When referring to files inside a sub-theme, they will always start with ./themes/THEMENAME/, where THEMENAME is the machine name of your sub-theme. They will continue to specify the full path to the file or directory inside it. For example, the primary file Drupal uses to determine if a theme exists is: ./themes/THEMENAME/THEMENAME.info.yml.
  2. Rename ./themes/THEMENAME/THEMENAME.starterkit.yml to match ./themes/THEMENAME/THEMENAME.info.yml.
    • Open this file and change the name, description and any other properties to suite your needs. Make sure to rename the library extension name as well: THEMENAME/framework.
  3. Rename ./themes/THEMENAME/THEMENAME.libraries.yml.
    • (Optional) If you plan on using a local precompiler (i.e. Less or Sass) then uncomment the appropriate JavaScript entries inside this file to enable the assets provided by the Bootstrap Framework.
  4. Rename ./themes/THEMENAME/THEMENAME.theme.
  5. Rename ./themes/THEMENAME/config/schema/THEMENAME.schema.yml
    • Open this file and rename - THEMENAME.settings: and 'THEMETITLE settings'
  6. Rename ./themes/THEMENAME/config/install/THEMENAME.settings.yml
    • (Optional) If you plan on using a local precompiler (i.e. Less or Sass) then you will need to disable the cdn_provider cdn_provider theme setting. You can do this several different ways, but it's recommended that you uncomment the following line in this file so the CDN Provider is automatically disabled when your sub-theme is installed: 
      # Disable the CDN provider so compiled source files can be used.
cdn_provider: ''

WARNING: Ensure that the .starterkit suffix is not present on your sub-theme's .info.yml filename. This suffix is simply a stop gap measure to ensure that the bundled starter kit sub-theme cannot be enabled or used directly. This helps people unfamiliar with Drupal avoid modifying the starter kit sub-theme directly and instead forces them to create a new sub-theme to modify.

Using Source Files

By default, the starterkit is designed to be used with a CDN Provider for quick setup.

While there are a multitude of different approaches on how to actually compile the Bootstrap Framework source files, this base-theme does not and will not provide templates or suggest specific tools to use. It is up to you, the developer, to figure out which solution is best for your particular needs.

LESS

SASS

Compile

Download and extract the source files into the root of your new sub-theme: ./themes/THEMENAME. After it has been extracted, the directory should be renamed (if needed) so it reads ./themes/THEMENAME/bootstrap.

If for whatever reason you have an additional bootstrap directory wrapping the first bootstrap directory (e.g. ./themes/THEMENAME/bootstrap/bootstrap), remove the wrapping bootstrap directory. You will only ever need to touch these files if or when you upgrade your version of the Bootstrap Framework.

WARNING: Do not modify the files inside of ./themes/THEMENAME/bootstrap directly. Doing so may cause issues when upgrading the Bootstrap Framework in the future.

Depending on which precompiler you chose, you should have a less/style.less or scss/style.scss file respectively. This file is the main compiling entry point. Follow further instructions provided by the README.md inside the less or scss folder.

Override Settings

Please refer to the Theme Settings topic.

Override Templates

Please refer to the Templates and Plugin System topics.

Enable Your New Sub-theme

In your Drupal site, navigate to admin/appearance and click the Enable and set default link next to your newly created sub-theme. Now that you've enabled your starterkit, please refer to the starterkit's documentation page to customize.

Source docs/Sub-Theming.md