www.aleph1.co.uk Git - yaffs-website/blob - web/themes/contrib/bootstrap/docs/Sub-Theming.md

   1 <!-- @file Instructions on how to sub-theme the Drupal Bootstrap base theme. -->
   2 <!-- @defgroup sub_theming -->
   3 # Sub-Theming
   4
   5 If you haven't already installed the Drupal Bootstrap theme, read
   6 the @link getting_started Getting Started @endlink topic. Below
   7 are instructions on how to create a [Drupal Bootstrap] based sub-theme.
   8 There are several different variations on how to accomplish this task, but this
   9 topic will focus on the two primarily and most common ways.
  10
  11 {.alert.alert-warning} **Warning** You should never modify any theme or
  12 sub-theme that is packaged and released from Drupal.org, such as Drupal
  13 Bootstrap. If you do, all changes you have made will be lost once that theme is
  14 updated. Instead, you should create a subtheme from one of the provided
  15 starterkits (this is considered a best practice). Once you've done that, you
  16 can override CSS, templates, and theme processing.
  17
  18 #### Choose a Starterkit {#starterkit}
  19
  20 - @link sub_theming_cdn CDN Starterkit @endlink - uses the "out-of-the-box"
  21   CSS and JavaScript files served by the [jsDelivr CDN].
  22 - @link sub_theming_less Less Starterkit @endlink - uses the
  23   [Bootstrap Framework] [Less] source files and a local [Less] preprocessor.
  24 - @link sub_theming_sass Sass Starterkit @endlink - uses the
  25   [Bootstrap Framework] [Sass] source files and a local [Sass] preprocessor.
  26
  27 Once you've selected one of the above starterkits, here's how to install it:
  28
  29 1. Copy over one of the starterkits you have chosen from the
  30    `./bootstrap/starterkits` directory into the `themes` directory.
  31 2. Rename the directory to a unique machine readable name. This is your
  32    sub-theme's "machine name". When referring to files inside a sub-theme,
  33    they will always start with `./THEMENAME/`, where `THEMENAME` is the machine
  34    name of your sub-theme. They will continue to specify the full path to the
  35    file or directory inside it. For example, the primary file Drupal uses to
  36    determine if a theme exists is: `./THEMENAME/THEMENAME.info.yml`.
  37 3. Rename `./THEMENAME/THEMENAME.starterkit.yml` to match
  38    `./THEMENAME/THEMENAME.info.yml`.
  39 4. Rename `./THEMENAME/THEMENAME.libraries.yml`
  40 5. Rename `./THEMENAME/THEMENAME.theme`.
  41 6. Open `./THEMENAME/THEMENAME.info.yml` and change the name, description and
  42    any other properties to suite your needs. Make sure to rename the library
  43    extension name as well:  `THEMENAME/framework`.
  44 7. Rename the sub-theme configuration files, located at:
  45    `./THEMENAME/config/install/THEMENAME.settings.yml` and
  46    `./THEMENAME/config/schema/THEMENAME.schema.yml`.
  47 8. Open `./THEMENAME/config/schema/THEMENAME.schema.yml` and rename
  48    `- THEMENAME.settings:` and `'THEMETITLE settings'`
  49
  50 {.alert.alert-warning} **WARNING:** Ensure that the `.starterkit` suffix is
  51 not present on your sub-theme's `.info.yml` filename. This suffix is simply a
  52 stop gap measure to ensure that the bundled starter kit sub-theme cannot be
  53 enabled or used directly. This helps people unfamiliar with Drupal avoid
  54 modifying the starter kit sub-theme directly and instead forces them to create
  55 a new sub-theme to modify.
  56
  57 #### Enable Your New Sub-theme {#enable}
  58 In your Drupal site, navigate to `admin/appearance` and click the `Enable and
  59 set default` link next to your newly created sub-theme. Now that you've
  60 enabled your starterkit, please refer to the starterkit's documentation page
  61 to customize.
  62
  63 [Drupal Bootstrap]: https://www.drupal.org/project/bootstrap
  64 [Bootstrap Framework]: https://getbootstrap.com/docs/3.3/
  65 [jsDelivr CDN]: http://www.jsdelivr.com
  66 [Less]: http://lesscss.org
  67 [Sass]: http://sass-lang.com