Template structure

This section is about the Bulkit File structure. Learning more about it will help setup the template quickly and easily.

Global structure

bulkit/
├── src/
│   ├── assets/
│   │   ├── font/
│   │   ├── img/
│   │   ├── js/
│   │   ├── sass/
│   │   ├── scss/
│   │   │   ├── abstracts/
│   │   │   ├── commerce/
│   │   │   ├── components/
│   │   │   ├── features/
│   │   │   ├── layout/
│   │   │   ├── sections/
│   │   │   ├── utilities/
│   │   │   └── core.scss
│   │   └── vendor/
│   ├── data/
│   ├── layouts/
│   ├── pages/
│   └── partials/
├── gulpfile.js
├── package.json
└── pnpm-lock.yaml

The directory structure can seem unusual for someone who is not used to build tools. We will break each part of it, so you understand how everything works.

Assets folder

bulkit/
├── src/
│   ├── assets/
│   │   ├── font/
│   │   ├── img/
│   │   ├── js/
│   │   ├── sass/
│   │   ├── scss/
│   │   │   ├── abstracts/
│   │   │   ├── commerce/
│   │   │   ├── components/
│   │   │   ├── features/
│   │   │   ├── layout/
│   │   │   ├── sections/
│   │   │   ├── utilities/
│   │   │   └── core.scss
│   │   └── vendor/

The main reason we are working with pnpm and gulp is that we want to keep our development process clean, as well as our dependencies management. This kind of setup highly increases the project's code maintainability and scalability. However, you'll be sometimes in a situation where you could need assets that are not served via pnpm or any package manager. That is the role of the vendor folder. You can add to it any external CSS, js, fonts or data that you will need to use in your project. However, always prefer the pnpm method when adding new assets. Use the assets folder only if you can't fetch your required dependency with pnpm.

Bulma folder

bulkit/
├── sass/
│   ├── sass/
│   └── bulma.sass

When you installed the project by doing pnpm install, you also installed Bulma 0.9.1 as a project dependency. All Bulma framework Sass source files are there. You can customize them to fit your needs or leave them as they are. If you do so, you will get the standard Bulma version (identical to the CSS file you can find in the Bulma distribution folder in the official repository) when you build the project. We provided this option as numerous developers want to have control on this for code optimization purposes.

WARNING

Edit the Bulma source files only if you know what you are doing as any faulty customization may completely break the layout.

Layouts folder

bulkit/
├── src/
│   └── layouts/

All the HTML layouts resides in this folder. For a more concise code, Bulkit uses a flat file compiler named Panini, by Zurb. Panini makes it easy to break your layouts into several reusable components, preventing you to go through every page to make your changes. You can find more information about zurb/panini by visiting the official repository. Bulkit follows the panini pattern for the HTML file structure.

the layouts folder holds all the template layouts. It is mandatory to have at least one layout, and it should always be named default.html. Additional layouts can have the names you want, but don't forget the .html extension. A layout acts as container providing the same base for a set of similar pages.

Pages folder

bulkit/
├── src/
│   └── pages/

The pages folder holds all the template pages. Pages are focused on content. They are related to a layout and automatically appended to it by panini when the page is served. You will always find the same statement at the top of each page's code :

---
layout: default
title: This is the page title
---

The layout statement tells panini which layout to use to serve the page. The title element is a string that gets inserted as the page title when panini has finished assembling the page parts together. Now that we had a look to panini's basic features let's dive into the Bulkit HTML files :

Component pages

Bulkit features 45 component pages which feature numerous UI elements and variations. These pages reside inside the Demo-Kit. These pages are named following this naming convention: _components_category_component.html . Each category features different components and variations. You'll find detailed explanations and code examples that you can immediately copy to start developing. The following categories are available:

Layout

Features building blocks that are relevant to layout such as Grid system, Navbars, Video background, Headers, Footers, Typography and Colors.

Sections

Features pre-built sections that you can copy and paste in your project pages, with little or no customization needed. Available sections are: Features sections, Pricing sections, Team sections, Testimonials sections, Client grids, Animated counters and Carousel sections.

Basic UI

Features pre-built first level components that you can easily reuse such as: Cards, Buttons, Dropdowns, Lists, Modals, Tabs & pills, Accordions, Badges & labels and Popups.

Advanced UI

Features pre-built first level components that you can easily reuse such as: Tables, Timeline, Boxes, Lists, and Messages.

Forms

Features pre-built inputs and form controls to help you build any kind of form including: Inputs, Controls, Form layouts, and File uploader.

Icons

Each page in this section lists the different icon collections Bulkit features, with their embed code. Available sets are Icons Mind, Font Awesome, Simple line Icons and Material Icons.

Partials folder

bulkit/
├── src/
│   └── partials/

The partials folder holds all your HTML partials. Partials are chunks of code that you want to reuse as is across your application : it can be a button, a navbar, a content section or whatever you want. Note that you can create as many sub-folders as you want to organize your partials. You simply have to make sure that your partial names are unique. Partials are named like HTML files : navbar.html. When you want to call a partial in one of your layouts or pages use the following expression : {{> partial-name}}. You don't have to mention the path, even if it is nested in several sub-folders, panini will find it. Also note that you don't have to add the HTML extension in your partial call.

Images

bulkit/
├── src/
│   ├── assets/
│   │   └── img/

All the project images live in this folder. It can have as many sub-folders as you want. When you build the projects, all these images are automatically transferred to the right location by Gulp. We will see that a bit later.

JS

bulkit/
├── src/
│   ├── assets/
│   │   ├── js/
│   │   │   ├── components/
│   │   │   ├── extensions/
│   │   │   ├── features/
│   │   │   ├── form/
│   │   │   ├── utilities/
│   │   │   └── main.js

All of Bulkit own javascript files live in this folder. Edit them to change the template functionality.

SCSS

bulkit/
├── assets/
│   ├── scss/
│   │   ├── abstracts/
│   │   │   └── _*.scss
│   │   ├── commerce/
│   │   │   └── _*.scss
│   │   ├── components/
│   │   │   └── _*.scss
│   │   ├── features/
│   │   │   └── _*.scss
│   │   ├── layout/
│   │   │   └── _*.scss
│   │   ├── sections/
│   │   │   └── _*.scss
│   │   ├── utilities/
│   │   │   └── _*.scss
│   │   ├── *.scss

Bulkit relies on the powerful Sass features, letting you handle complex styles in a breeze. Bulkit relies on a modular SCSS structure. You need to import all the SCSS partials into your core file. This how SCSS files are organized.

Core and partials

There are two main types of SCSS files in Bulkit : Core and Partials.

Partial files

Partial files

Partial SCSS file names always start with an underscore like this: _testimonials.scss . They act as chunks of code that you can import only if you need them. Of course some of them are mandatory for the project to work. For example, if you need to display cards in your project, you can import scss/components/_cards.scss to have access to the card components in your layout. We will see later that you need to load them in a specific order to avoid styling issues. SCSS partials are of several types:

• Global partials: partials that are common to all demos : _variables.scss. Importing _variables.scss is mandatory.
• Theme partials: 10 Themes are built in out of the box in Bulkit. Default is scss/partials/_themes-main.scss . You have to import a theme in your core SCSS file. Otherwise your site will be broken.
• Layout partials: Layout partials are all mandatory. You have to import them in order to setup a basic layout for your website.
• Component partials: Component partials are optional. However, you will need to add some to your project to hold the content you are planning publish. Bulkit's approach is modular, so you pick only what you use.
• Feature partials: Bulkit is shipped with features such as icon boxes, CTA blocks and many more. Each feature has its own SCSS file that you can import if you need to use it.
• Section partials: Section partials are related to content served on Bulkit pages. Each demo kit used to have its own stylesheet, which is was shared with others. For example, the Startup kit had its own partial named _startup.scss. You could find it in scss/page/_startup.scss. This is over in Bulkit since 4.3. The files in there have changed name and role. They now are a collection of reusable elements that you can use in any page or any kit.

Core files

The core SCSS file is the heart of Bulkit's styles. Its main purpose is to centralize all styles. Every time you make a change in a partial file, it impacts the outputted core.css (or any other theme like azur.scss) file resulting from the compilation process. Core files start with imports of other partial SCSS files. Here is an example import statement:

/*! Bulkit | 5.1 | CSS Ninja */

/* ==========================================================================
Core Theme
========================================================================== */

/* ==========================================================================
0. CSS Imports
========================================================================== */

//1. Bulkit main variables
@import "abstracts/variables";
@import "abstracts/themes-main";
@import "abstracts/shadows";

//2. Bulma source sass
@import "../sass/bulma.sass";

//3. Layout styles
@import "layout/all";

//4. Components styles
@import "components/all";

//5. Features styles
@import "features/all";

//6. Sections styles
@import "sections/all";

//7. Commerce styles
@import "commerce/all";

//8. CSS Utilities
@import "utilities/all";

//9. Global Media Queries
@import "layout/responsive";

//10. Slick carousel optimization
$slick-font-path: "/assets/fonts/";
$slick-loader-path: "/assets/fonts/";

@import "../../../node_modules/slick-carousel/slick/slick.scss";
@import "../../../node_modules/slick-carousel/slick/slick-theme.scss";

TIP

Notice how partials are imported. Whereas the actual partial file name starts with an underscore and ends with a .scss extension, when you write imports inside your core.scss file, you have to remove the underscore and the .scss extension.

Imports

Let's break a bit the list of imports we saw above, so we can understand how the global stylesheet is structured and how it impacts the final outputted style.

1. The first line imports scss/abstracts/_variables.scss. Importing this file is mandatory since it contains all core color variables. Without it, nothing will work and your pages will be broken.
2. The second line is also part of mandatory imports. It imports the selected theme from abstracts/_themes-main.scss. Each one of these theme files is used by one specific stylesheet. Each theme can be linked to one or several core files. For more consistency, we linked each theme to a single core file (beside the exception that we mentioned above). You can learn more about themes in the Theming section.
3. The following lines import layout partials from layout/_*.scss. All of these imports are mandatory for the theme to work, as they handle all animations, navbars, sections, footer and even the pre-loader 4.The components imports are up to you. However some of them like forms should normally be imported by everyone because... everybody needs forms on a website. But it is still up to you to decide which components you will need or not in your project. The component imports are followed by extensions imports, if you need to use some special features.
4. Feature imports handle small UI elements like Icon boxes, side text layouts, CTA boxes etc...
5. Section imports handle unique sections that can be reused across your landing pages.
6. Commerce imports handle the styles of ecommerce pages.

Link the core

Once you finished writing your imports, and adding the basic CSS resets you want in your core file, you are ready to setup a new page. As we stated before, as soon as Gulp is running, your core file is immediately outputted into a compiled CSS file. The CSS chunks from partials are appended one after another following the order defined in the imports. To import the core, just add a stylesheet link to the compiled CSS inside the head tags of one of your layout files, like src/layouts/default.html:

<link rel="stylesheet" type="text/css" href="{{root}}assets/css/core.css" />

TIP

Notice the {{root}} elements which tells panini to get back to the root of the project to find the CSS stylesheet.

Root files

There also a few files sitting at the root of the project that we need to discuss before getting into serious business:

• gulpfile.js : Gulp will use this file to perform all the tasks it is supposed to accomplish.
• package.json : Lists all your project's dependencies and gives useful metadata.
• pnpm-lock.yaml : Automatically generated for any operations where pnpm modifies either the node_modules tree, or package.json. It describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates.