Base-2018 is a clean theme for Bolt, built on top of Bulma. To learn more about specific Bulma components, check out the Bulma Documentation.
The documentation laid in this README will cover how to get started with Foundation for Bolt and how some Foundation components, are integrated with Bolt.
Base-2018 comes with all of the great features that are found in Bolt, the Bulma framework, and a few things more. Simply put, if it works in Bulma, it will work in Bulma for Bolt. The theme also includes:
- Sass(scss) or CSS Versions
- Optional Yarn and Gulp Support
- And much, much more!
You can use whatever you want – seriously. You can use Gulp, Yarn, Codekit or nothing at all. It’s completely up to you how you decide to build your theme – Bulma for Bolt will stay out of your workflow as much as possible.
This theme does include Sass, Javascript and Gulp files, and is optimized for a Gulp-based workflow. To get the most out of Foundation for Bolt, Gulp is highly recommended. However, if you're not using Gulp yet, you can also modify the compiled CSS files as is.
These are the most important files, included in this theme.
.
├── css/
│ ├── bulma.css - The compiled Bulma CSS framework
│ └── theme.css - Theme-specific CSS
├── js/
│ ├── app.js - Theme-specific Javascript
│ └── normalizeBrightness.js - A required javascript file
├── partials/
│ ├── _aside.twig - Partial for the sidebar. With fixed content, or widgets
│ ├── _footer.twig - Partial for the footer below every page
│ ├── _fresh_install.twig - Partial that's shown on fresh installs with some instructions
│ ├── _header.twig - Partial for the header banner with the site title.
│ ├── _master.twig - Twig template, that is uses to 'extend' all pages (See 'template inheritance')
│ ├── _navbar.twig - Partial with the navigation bar shown on top of every page
│ ├── _record_meta.twig - Partial with meta-information shown at the top of a page or entry
│ ├── _recordfooter.twig - Partial with meta-information below a page or entry
│ ├── _sub_field_blocks.twig - Partial with blocks, used by `_sub_fields.twig`
│ ├── _sub_fields.twig - Partial used to render contenttypes with an undertermined amount of fields
│ ├── _sub_menu.twig - Partial with macro for rendering the drop-down menu
│ ├── _sub_menu_footer.twig - Partial with macro for rendering the menu in the footer
│ ├── _sub_pager.twig - Partial with the markup for the pagination ([1|2|3|…])
│ ├── _sub_recent_records.twig - Partial for the "latest records" block
│ └── _sub_taxonomylinks.twig - Partial with the markup for the links to taxonomies like categories and tags
├── source/
│ ├── javascript/
│ │ └── app.js - Source app.js file
│ ├── node_modules/
│ ├── scss/
│ │ ├── _breakpointdebug.scss
│ │ ├── _settings.scss
│ │ ├── _typography.scss
│ │ ├── bulma.scss
│ │ └── theme.scss
│ ├── gulpfile.js - Build task script for Gulp.
│ ├── package.json - Configuration for used Node / Gulp packages.
│ └── yarn.lock
├── README.md
├── index.twig
├── listing.twig
├── not-found.twig
├── page.twig
├── record.twig
├── search.twig
└── theme.yml
No need to install anything. This theme comes with Bolt. Don't forget to set
theme: base-2018 in your config.yml file, if it doesn't show up already.
This theme was developed to be as "tinker friendly" as possible. Depending on your area of expertise and experience with different front-end development techniques, you can modify the CSS of this theme on different 'levels':
- If you're familiar with Bulma and Gulp, you can finetune which parts of
Bulma are included, as well as all their settings. See the
source/scss/bulma.scssandsource/gulpfile.jsfiles. - If you do know a bit of SCSS, you can work in
source/scss/theme.scssandsource/scss/_settings.scssfiles. - Otherwise you can just make your changes in the compiled css at
css/theme.css.
The templates themselves are the .twig files in the root of the theme folder,
as well as the additional helper files in the partials folder.
All HTML parts of the theme are made in Twig. If you're not familiar with Twig yet, be sure to read the Bolt documentation on Twig, as well as the official Twig documentation.
This theme uses a concept called 'template inheritance'. From other themes or CMS'es, you might be familiar with seeing each page 'include' a header and a 'footer'. Instead, we have one 'master' template, which are extended by each of the different templates. You can read more about this concept on the Twig site - Template Inheritance or here: Dealing With Themes And Layouts With Twig
For example, take a look at one of the simpler templates, record.twig:
{% extends 'partials/_master.twig' %}
{% block main %}
<h1>{{ record.title }}</h1>
{{ block('sub_fields', 'partials/_sub_fields.twig') }}
{{ include('partials/_recordfooter.twig', { 'record': record }) }}
{% endblock main %}You'll notice the first line that states that the template 'extends' the
_master.twig partial. The rest of the template is the {% block %}, which
overrides the 'main' block in the master template. Inside the block is just an
<h1> element with the record title, a sub_fields block (defined in
partials/_sub_fields.twig) that will output the fields that are defined for
this ContentType, and it closes with an include of _recordfooter.twig to
display some meta data, like the author, date and permalink.
As you can see, we can still use 'include' for small blocks of HTML, even though we're using template inheritance. This way we can keep our themes very structured and organized.
Because this is a general purpose theme, we try to make it work without problems
for any defined ContentType. This means we'll need to render all available
fields in the template without knowledge of which fields are defined exactly.
To do this, we're using the _sub_fields.twig partial. Simply said, this
partial goes over all fields in the ContentType, and outputs them in a generic
way. It's used like this:
{% with { 'record': record, 'common': true, 'extended': true, 'repeaters': true } %}
{{ block('sub_fields', 'partials/_sub_fields.twig') }}
{% endwith %}The with tag is used to scope variables: This way they will be available
within the block, but not outside. The partial has a few "options" you can set
this way:
| Option | Description |
|---|---|
record |
The Record to use in the display. Defaults to record |
common |
Whether or not to include common fields like 'text', 'html', 'textarea', 'image' and 'video' in the output. Defaults to true |
extended |
Whether or not to include all other regular fields (like 'date', 'select' and others) in the output. Defaults to false |
repeaters |
Whether or not to include repeater fields in the output. Defaults to false |
exclude |
field names to exclude, even though they might otherwise be included |
skip_uses |
By default the field that's used as the slug is skipped, under the assumption that it corresponds to the title of the page. To disable this, set 'skipuses': false |
Note: templatefields are included in common and extended, where applicable.
In the diagram below, you'll see the wat most pages are structured. In this case,
index.twig. In the HTML, you will see it extends _master.twig, which can be found in
the partials/ folder. Inside this file, the global structure of all pages is laid out:
The basic HTML structure, and a handful of other included partials.
index.twig structure _topbar.twig
│
├─────────────────────────┴────────────────────────────────┤
┌────────────────────────────────────────────┬───────────────┐
_sub_menu.twig ──▶ │ Home link1 link2 link3 │______ [Search]│ ◀── _search.twig
├────────────────────────────────────────────┴───────────────┤
│••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••│
│•••••••••••••••••••••••(header image)•••••••••••••••••••••••│ ◀── _header.twig
│•••••••••••••••••••••••(name of site)•••••••••••••••••••••••│
│••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••│
│ ┌──────────────────(main content)─┐ ┌────────────(aside)─┐ │
│ │Lorem ipsum dolor sit amet │ │Lorem ipsum dolor │ │
│ │ │ │sit amet. Consec- │ │
│ │Consectetur adipiscing elit. Nunc│ │tetur adipiscing. │ │
│ │omni virtuti vitium contrario │ │ │ │
│ │nominehgpponitur. Non enim, si │ │Latest X │ │
│ │malum est dolor, carere eo malo │ │ - intellegetur │ │
│ │satis est ad bene vivendum. Duo │ │ - Expectoque │ │
│ │Reges: constructio interrete. │ │ - videantur │ │ ◀── _aside.twig
│ │ │ │ │ │
│ └─────────────────────────────────┘ │Latest Y │ │
│ ┌─────────────────────────────────┐ │ - intellegetur │ │
│ │Lorem ipsum dolor sit amet │ │ - Expectoque │ │
│ │ │ │ - videantur │ │
│ │Consectetur adipiscing elit. Nunc│ │ │ │
│ │omni virtuti vitium contrario │ │ │ │
┬ ├─┴─────────────────────────────────┴─┴────────────────────┴─┤
_footer.twig ──┤ │ (C) 2016 Home link1 link2 link3 │ ◀── _sub_menu.twig
┴ └────────────────────────────────────────────────────────────┘
├────────────────────────────┬─────────────────────────────────┤
│
_master.twig
This theme comes with its own configuration file, named theme.yml. In this
file you can set certain specific options for the theme, such as the default
images for the header, the position of the 'aside' sidebar, and the global
layout.
Finally, the last section defines the settings for which templates are used for which types of pages. The templates you will set in this config file will override the ones in the global app/config/config.yml, so beware!
# maintenance_template: maintenance_default.twig
homepage_template: index.twig
record_template: record.twig
listing_template: listing.twig
search_results_template: search.twig
notfound: notfound.twig
For details on which page is used when, see the next section in this document.
You are free to do what you want, when it comes to the .twig files. Out-of-the- box, this theme comes with a handful of templates, that correspond to the default ContentTypes when you have a fresh install of Bolt.
Most of the templates will be pretty straightforward, especially if you're familiar with the concept of Template Inheritance. The main templates are:
index.twig: Used as the frontpage or homepage of the site.listing.twig: This template is used for listing overviews of all kind, like/pagesfor all records in the 'pages ContentType' orcategory/moviesfor all records that have the 'movies' category assigned to them. Note that 'search' uses its own template, though.notfound.twig: This template is used as the template that's shown when the visitor hits a non-existing page on the website.page.twig: The detail page for a single record of the 'pages' ContentType. Automatically picked up by Bolt, if the name matches.record.twig: The "generic" detail page for a single record page. This is used as the fallback, if there's no specific template set for a single record page.search.twig: This page displays the search results and a search box, to search again.styleguide.twig: A sample page, showing most of the common typograhy options, form elements, as well as other components supplied by Foundation 6. Use your browser to go to/styleguideto view this page.
This theme uses Node, Yarn and Gulp to run the tasks to compile and minify the Sass an Javascript files. If you don't have Node, Yarn and Gulp yet, install them from Nodejs.org, Yarnpkg.com and Gulpjs.com.
To install the themes dependencies, run the following in the source directory:
yarn install
Now you can simply run yarn run gulp to compile the javascript and sass
files. This will build the files, and it will continue to monitor changes to
the .scss files. If you make a change, the compiled files will be updated
immediately. When you're ready to deploy, and put the site in production, be
sure to build the files and minify them:
yarn run gulp build
This will build the files that you can deploy, or put into your versioning system.
The build process has been tested on Yarn 1.5.1. If you do not have Yarn installed, or need to update it, see: https://yarnpkg.com/lang/en/docs/install/
And then go through the above steps again.
If you're interested to learn more about the process, these two tutorials on Gulp (which is what we use under the hood) might be of interest to you: