Individual files and directories

Read about each file and directory and their purposes.

Files and directories

Once you've created your subtheme, and before you just dive in, it's best to know how to utilize the Radix and Bootstrap.

Let's start by getting to know each directory and files that are significant to us we might want to work with. this is the SUBTHEME_NAME tree structure first when you create your subtheme:

/SUBTHEME_NAME
│
├── README.md
├── SUBTHEME_NAME.breakpoints.yml
├── SUBTHEME_NAME.info.yml
├── SUBTHEME_NAME.libraries.yml
├── SUBTHEME_NAME.theme
├── biome.json
├── build/
├── components/
├── config/
├── includes/
├── logo.svg
├── mix-manifest.json
├── node_modules/
├── package-lock.json
├── package.json
├── screenshot.png
├── src/
├── templates/
├── translations/
└── webpack.mix.js

We are not going to teach Drupal theme structure here, so we only dive into the files that Radix treats differently and explain them in detail.

• SUBTHEME_NAME.breakpoints.yml: the predefined default breakpoint definitions to be used with the Drupal breakpoints system, not directly related to Bootstrap breakpoints but would be useful when working with the responsive images and Drupal layouts.

• SUBTHEME_NAME.info.yml: This is a crucial file in any Drupal theme. It contains metadata about the theme, such as its name, description, core version compatibility, and any base themes or libraries it depends on.

• SUBTHEME_NAME.libraries.yml: This file declares all the Drupal libraries (CSS and JS files) that are used by the theme. Using SDC in the core, we might have less to do with this file than we used to since the assets will be shipped with the component itself.

• SUBTHEME_NAME.theme: This file is a PHP script and is used to include PHP logic that alters Drupal's default markup, styling, and behavior. It's used for theming customizations. but if you look into the file, you see a loop that would load all the files in includes directory. this is a conscious decision to keep things clean and separated, so any theme hooks should go inside the includes directory, e.g. block.theme or form.theme. Ideally, this file shouldn't be touched directly.

• biome.json: The JSON configuration file to modify the BiomeJS linting and formatting and messaging, the default is good as it is out of the box.

• mix-manifest.json: This file is generated by Laravel Mix and maps the compiled assets to their source files. No need to touch it.

• logo.svg: The SVG file of the theme's logo. You may update this file or upload a new logo from the /admin/appearance/settings/SUBTHEME_NAME

• webpack.mix.js: A configuration file for Webpack (Laravel Mix), used to compile and manage front-end assets like JavaScript, CSS and even move your files like fonts, images and more. Works as is out of the box, but feel free to modify it to your needs.

• package-lock.json & package.json: These are part of the NodeJS npm package manager. package.json lists all the node packages and the dependencies, while package-lock.json ensuring a consistent installation. If you want to install a new package, it should go into the package.json as a devDependency and you should never touch package-lock.json the file directly, it will be updated/built whenever you modify the package.json file or run npm install

• build/: This directory is the output of our npm run watch or npm run production commands, assets like our built CSS or JS files, and even images, fonts, icons and videos. you should not touch anything within this directory. You may look into webpack.mix.js file for more info. If you are using a CI/CD tool like CircleCI or similar, you should have this directory gitignored and let the deployment task build it.

• components/: This is the directory you'd want to work with your components. Out of the box, there's only one component called offcanvas within it, but you can copy over any components that you'd like to modify or create new components within this directory. We will cover the details of how to work with components later on.

• src/: Contains the source files (like SASS, JavaScript, fonts, images, icons, and videos) that are compiled into the assets used by the theme. The hierarchy of files and directories looks like this:

  • assets/: All your media and font assets should go in here when developing, e.g. fonts, images, icons, and images. It will be copied over into the build/ directory automatically. this directory will not be read directly by the theme, for development purposes only.

  • js/: Out of the box, it includes the _bootstrap.js and main.script.js but you can also add any other global (non-component) JS files here. ideally, you shouldn't need any new files to be created here but rather within components themselves.

    • _bootstrap.js: All the modules of Bootstrap that will be included in your final JS build, you may comment on any part that you wouldn't be using for performance reasons, otherwise you can keep it as is.

    • main.scripts.js: This is the main JS file that will be loaded globally on your website (check SUBTHEME_NAME.libraries.yml file to adjust it if needed). Out of the box, it initiates the Tooltip and Toast Bootstrap modules out of the box.

  • scss/: All of your global SASS files, are structured in the following way for easier maintenance:

    • base/: All your basic/global styling that can't be within a component could be defined here, note that you shouldn't start styling by skipping the components directory and doing everything in here, otherwise, why are you using a component-based theme?

      • _elements.scss: Global elements styling, e.g. for headings, buttons, links, etc.

      • _functions.scss: Global Sass @function declarations.

      • _helpers.scss: Any helper classes you might need throughout your project, e.g. container--custom or btn--extra-red or whatnot.

      • _mixins.scss: Global Sass @mixin declarations.

      • _typography.scss: Your custom typography, like your @font-face. Otherwise, your font-family names and adjustments should be defined in _variables.scss file similar to Bootstrap typography

      • _utilities.scss: This file is used to generate utility CSS classes, we have a couple of examples within the file already.

      • _variables.scss: All of your Bootstrap configurations like sizing, coloring, spacing and A LOT MORE go into this file, this is the file that you first need to look into when you start your project to utilize the Bootstrap power. One easy way to get started with this file is to check the Bootstrap main _variables.scss file (The one that ships with the Bootstrap NPM package and not your own theme's) and copy over whatever you need and adjust it to your own needs. Every Sass variable in Bootstrap includes the !default flag allowing you to override the variable’s default value in your own Sass without modifying Bootstrap’s source code. Copy and paste variables as needed, modify their values, and remove the !default flag. If a variable has already been assigned, it won’t be re-assigned by the default values in Bootstrap.

    • _bootstrap.scss: All the SASS modules of Bootstrap are included here, you may comment out those that you don't need, otherwise, you can keep it as is and no need to touch it.

    • _init.scss: init stands for Initiate, this file is the soul of all your SASS files, you would need this if you create a new SCSS file anywhere in the project more or less, since it loads your globally defined variables, mixins, functions and a lot more. So remember to import this file if you intend to use your Bootstrap within your components SASS file like so: `

      @import "../../scss/init";

    • main.style.scss: As the name suggests, the main style file of your theme is globally loaded, ideally shouldn't be touched since all SASS files should be loaded via its component but in case you need anything imported globally, you can use this file. Out of the box, it only loads all the Bootstrap SASS modules and the offcanvas component.

• templates/: Contains the Twig template files for Drupal itself. If you look into any of the files under the templates directory, you'll notice that it always include , embed or extends a radix component. The idea is that no *.html.twig file should be adjusted to load markup directly but rather points to a component.

• translations/: Contains translation files, allowing the theme to support multiple languages. For example, there is a nb.po file out of the box available (Norwegian bokmål), you may add any other language files here, it will be imported automatically (Check the SUBTHEME_NAME.info.yml file for the details)

• includes/: This directory contains additional theme files (*.theme) that the theme uses. These files or any other files that end with a .theme are automatically included in the main [SUBTHEME_NAME].theme file for specific functionalities. This is where you should define all your Drupal theme-specific hooks.

• config/: Contains configuration files that could be used for theming settings or other purposes. You probably wouldn't need to change a thing here.