BAS Style Kit Jekyll Theme
Jekyll theme for the BAS Style Kit.
These templates get packaged up into a Ruby Gem. This Gem is then used in other projects.
Installation
Add this line to your Jekyll site's Gemfile
:
gem "jekyll-theme-bas-style-kit"
And then execute:
$ bundle
Or install it yourself as:
$ gem install jekyll-theme-bas-style-kit
Finally, to use the theme, add this line to your _config.yml
file:
theme: jekyll-theme-bas-style-kit
Usage
Refer to Jekyll's theme documentation for general information.
Quick start
Add these lines to your _config.yml
file:
bas_style_kit_jekyll_theme:
attributes:
head_title:
default: 'Example service'
appended: ' - Example service'
head_description: 'Service to act as an example'
site_brand:
text: 'Example service'
href: '/'
site_development_phase: 'beta'
site_feedback_href: '/feedback'
legal_policies:
cookies_href: '/legal/cookies'
copyright_href: '/legal/copyright'
privacy_href: '/legal/privacy'
# Optional - add a custom CSS file with a relative URL
site_styles:
-
href: '/css/main.css'
type: 'local'
# Optional - add a custom JS file with a SRI value
site_scripts:
-
href: 'https://example.com/js/example.js'
integrity: 'abc123'
type: 'remote'
# Optional - enable web analytics
site_analytics:
id: '1234'
# Optional - choose between the `bsk-container` and `bsk-container-fluid` layout container
container: 'bsk-container'
To optionally add navigation menu items, add these lines to _data/menus.yml
:
site_navigation_primary:
- url: '#'
title: 'Item'
site_navigation_launcher:
- url: 'https://www.bas.ac.uk'
title: BAS Home
weight: 1
- url: 'https://example.com'
title: Related service
weight: 3
Standard page
To create a page in an application or website based on the standard BAS page structure, create an application layout
(e.g. _layouts/app.html
) with the following:
---
layout: layouts/bas-style-kit/bsk--standard.html
---
To base all pages this layout add these lines to your _config.yml
file:
defaults:
-
scope:
# An empty string here means all files in the project
path: ""
values:
layout: "app"
Use a page pattern
To create a page in an application or website based on a page pattern, create a view
(e.g. views/error.pug
) with the following:
---
layout: views/bas-style-kit/[page-pattern]
---
Where [page-pattern]
in the extends value is the name of a page pattern, for example:
---
layout: views/bas-style-kit/bsk--page-not-found
---
Use a component pattern
To include a component pattern, call the relevant include with an required parameters. For example:
{% include bas-style-kit/bsk--pattern--item-type-header.html item_type="Item type" item_title="Item title" %}
Patterns
Patterns are used to define preferred ways to pass information to users, and ask information from users, in a consistent way. See the Style Kit documentation for more information.
There are two types of pattern used in the Style Kit and these templates:
- pages - standalone pages designed to be used without customisation using Views
- components - inline elements designed to be used without customisation using Includes
Page patterns
These template include Views for all page patterns. In most cases all variants of a pattern use the same view, but with different options using variables and/or page content.
See the Style Kit documentation for general information on using these patterns.
'page not found' pattern
No configuration options.
'service unavailable' pattern
Use page content for:
- contact information
Optionally, use page content for:
- details of alternative services
Optionally, use a pattern_availability
page variable for setting the availability line:
- a value of
closed
will show conventional text - a value of
replaced
will show conventional text - no value will show conventional text
'problem with this service' pattern
Use page content for:
- contact information
Optionally, use page content for:
- details of alternative services
'start' pattern
Use page content for:
- a list of needs the service caters for, as a list wrapped in a section with the
bsk-service-uses
class [1] - a call to action, as a link wrapped in a section with the
bsk-call-to-action
class [2]- if the call to action should be a 'Sign in to start' button use [3]
- contact information, as text wrapped in a section with the
bsk-more-information
class [4]
Optionally, use page content for:
- 'before you start' information, wrapped in a section with the
bsk-before-you-start
class [5]
Note: If not already included via a layout, include Font Awesome to show the ORCID symbol.
[1]
<section class="bsk-service-uses">
<h2 class="bsk-h3">Use this service to:</h2>
<ul>
<li>access some information</li>
<li>perform an action</li>
<li>etc.</li>
</ul>
</section>
[2]
<section class="bsk-call-to-action">
<a class="bsk-btn bsk-btn-primary bsk-btn-lg" href="#">
Start Now
<i class="fa-fw fas fa-chevron-right"></i>
</a>
</section>
[3]
<section class="bsk-call-to-action">
<button class="bsk-btn bsk-btn-ms-account bsk-btn-lg">
<object class="bsk-ms-pictogram" type="image/svg+xml" data="https://cdn.web.bas.ac.uk/bas-style-kit/{{ site.data.bas-style-kit.bsk-vars.bsk_version }}/img/logos-symbols/ms-pictogram.svg"></object>
Sign in to start
<i class="fa-fw fas fa-chevron-right"></i>
</button>
<p class="bsk-sign-in-hint bsk-text-muted">Use the account you use for your NERC email to sign into this service.</p>
</section>
[4]
<section class="bsk-more-information">
<h2 class="bsk-h3">More information</h2>
<p>Contact the <a href="#">Sample Team</a> for information and help on how to use [website or application].</p>
</section>
[5]
<section class="bsk-before-you-start">
<h2 class="bsk-h3">Before you start</h2>
<p>You need some information to use this service.</p>
</section>
'sign in' pattern
Use page content for:
- a call to action, as a page variable [1]
---
layout: views/bas-style-kit/bsk--sign-in-microsoft
call_to_action_href: #
---
Component patterns
These templates use includes for all component patterns. Include parameters are used for customising each instance of the component.
See the Style Kit documentation for general information on using these patterns.
Item type header pattern
Parameters:
-
item_type
the type or kind of thing the item is, e.g. if the item is a person, it's type is 'person' -
item_title
a label specific to the item, e.g. if the item is a person their name
{% include bas-style-kit/bsk--pattern--item-type-header.html item_type="Item type" item_title="Item title" %}
ORCID iD pattern
Parameters:
-
orcid_id
the ORCID iD of an individual as a URL
{% include bas-style-kit/bsk--pattern--orcid-id.html orcid_id="https://sandbox.orcid.org/0000-0001-8373-6934" %}
Note: If not already included via a layout, include Font Awesome to show the ORCID symbol.
Using custom CSS/JS
Support is provided for loading additional CSS an/or JavaScript resources, such as application or website specific styling or interactivity, either as references to files.
This support is available in all layouts which inherit from the bsk--basic.html
layout.
For file resources, variables are provided for adding URLs and optional SRI values. Files will be included in the relevant block automatically, after the Style Kit's own resources if a Style Kit layout is used.
- CSS resources are outputted at the end of the
<head>
element - JS resources are outputted at the end of the
<body>
element
Add these lines to your _config.yml
file:
bas_style_kit_jekyll_theme:
attributes:
site_styles:
-
href: '/css/main.css'
type: 'local'
site_scripts:
-
href: 'https://example.com/js/example.js'
integrity: 'abc123'
type: 'remote'
Resource objects
Resource objects have the following properties:
Property | Data Type | Required | Allowed Values | Example Value |
---|---|---|---|---|
href |
String | Yes | Any URL |
/css/app.css / https://example.com/js/app.js
|
type |
String | Yes |
local or remote
|
local |
integrity |
String | No | Any SRI value | sha256-ClILH8AIH4CkAybtlKhzqqQUYR4eSDiNTK5LIWfF4qQ= |
The integrity
property is used to specify a
Subresource Integrity (SRI) value for
a resource. If specified an integrity
attribute and will be added to the generated markup. A crossorigin
attribute will also be added for
Cross-Origin Resource Sharing (CORS) support with a
hard-coded, anonymous
, value.
Navigation menu items
When using the bsk--standard.html
layout, a navbar is included
as part of the 'standard header', which consists of a cookie banner, navbar and site development phase banner.
This navbar consists of three menus (and other elements, documented elsewhere):
- a primary navigation menu - aligned left, after brand elements
- a secondary navigation menu - aligned right, before the launcher menu
- a navigation launcher menu - aligned right, after the secondary navigation menu
The navigation launcher is a restricted menu, used to link to other BAS websites and applications. By default it contains links to the BAS public website and the BAS data catalogue. Other websites and applications can be added as well where relevant.
The primary and secondary navigation menu's support:
The navigation launcher menu, which is implemented as a drop-down menu, supports:
All navigation menus are implemented using the Jekyll menus plugin.
- primary navigation menu items should be added to the
site_navigation_primary
menu - secondary navigation menu items should be added to the
site_navigation_secondary
menu - navigation launcher menu items should be added to the
site_navigation_launcher
menu
Note: Menu items are only recursed once, deeper objects will be ignored.
Navigation branding
Navbars are also used to display the name/identity of a website or application, to remind users where they are. These elements are referred to as 'brand' elements within the Style Kit.
In the 'standard header', navbar brand elements are shown on the far left.
Supported brand elements:
-
brand text - set using the
bas_style_kit_jekyll_theme.attributes.site_brand.text
config variable -
brand image - set using the
bas_style_kit_jekyll_theme.attributes.site_brand.img
config variable
Brand elements can be used together or individually, with fix classes applied automatically as needed.
Brand elements are linked to a location specified by the bas_style_kit_jekyll_theme.attributes.site_brand.href
config
variable, which should be the index of each website or application (i.e. /
).
Site development phase
The site development phase reflects the stage of development for a website or application, e.g. alpha or live. They are described in the Style Kit here.
For websites or applications that are not firmly in the 'live' phase, a banner should be shown to inform users and request feedback. This forms part of the 'standard header' of cookie banner, navbar and site development phase banner.
In these templates, the bas_style_kit_jekyll_theme.attributes.site_development_phase
config variable is used to
specify the current phase for a website or application. When using the bsk--standard.html
layout, a banner will be
shown automatically based on this variable.
To disable this banner, set the bas_style_kit_jekyll_theme.attributes.site_development_phase
config variable to
live-stable
. This isn't a real phase but separates a newly released website or application from something more mature.
For example:
bas_style_kit_jekyll_theme:
attributes:
site_development_phase: 'alpha'
Experimental development phase
Alternatively, the bas_style_kit_jekyll_theme.attributes.site_development_phase
config variable can be set to
experimental
to indicate where an website or application is used for staging or other development/testing activities.
For example:
bas_style_kit_jekyll_theme:
attributes:
site_development_phase: 'experimental'
Website analytics
To include the Google Analytics universal tracking library (gtag), set the
bas_style_kit_jekyll_theme.attributes.site_analytics.id
property to relevant Google Analytics property ID.
Note: When used, the anonymise IP option in Google Analytics is enabled by default.
For example:
bas_style_kit_jekyll_theme:
attributes:
site_analaytics:
id: '123abc'
Components
Components in these templates are structured according to Jekyll's conventions (e.g. layouts in _layouts/
). They are
also namespaced in a bas-style-kit
directory (e.g. _layouts/bas-style-kit/
). Components that are specific to the
Style Kit are prefixed with bsk--
.
Views
Views are used for implementing page patterns. They are essentially layouts but with predefined page content relevant to each pattern.
Within Jekyll, views are implemented as layouts. To use a view, create a page with the relevant 'view' layout.
---
layout: views/bas-style-kit/page-not-found
---
Views for some pattern variants can be used as-is, others require variables or page content to be set as well. See the Page patterns section for more information.
Layouts
Refer to Jekyll's documentation for general information.
Layouts are 'base' templates from which views or other layouts inherit. Layouts in this theme are hierarchical, with each layout extending the last in this order:
-
blank.html
: lowest level layout, intentionally as minimal as possible and not intended for direct use, unless non-HTML output is needed -
html.html
: defines a minimal, accessible, HTML5 structure with some recommended best practices for cross-platform compatibility -
bsk--base.html
: intentionally implements the BAS Style Kit as minimally as possible and not intended for direct use, unless the bsk_standard.j2 layout is unsuitable -
bsk--standard.html
: defines an opinionated, conventional, page layout with a 'standard' header/footer, recommended as a base for application/website layouts -
bsk--standard-page.html
: defines an opinionated, conventional, content page layout, recommended as a base for content type websites, such as documentation
For example:
---
layout: bas-style-kit/html
---
Page content
Layouts inheriting from the bsk--standard
layout can add additional classes to the #main-content
element by setting
the main_content_classes
variable in each layout.
For example:
---
layout: bas-style-kit/bsk--standard
main_content_classes: foo
---
Page content
Includes
Refer to Jekyll's documentation for general information.
This theme uses includes extensively to give fine grained control over how elements such as the navbar behave, including both their content and structure.
Includes are often used conditionally using a related configuration option, to be disabled more easily.
Data files
Refer to Jekyll's documentation for general information.
This theme uses data files to define CSS and JavaScript resources to load and for some variables about the theme.
All data files use the .yml
(Yaml) extension and are namespaced using a bas-style-kit/
directory - i.e. a data
element foo
in the data file bsk-vars.yml
is available as site.data.bas-style-kit.bsk-vars.foo
.
Variables
Refer to Jekyll's documentation for general information.
Style Kit specific variables
Variable | Fully Qualified Variable | Purpose | Example | Notes |
---|---|---|---|---|
theme_version |
site.data.bas-style-kit.bsk-vars.theme_version |
Version of this theme | 0.3.0 |
- |
bsk_version |
site.data.bas-style-kit.bsk-vars.bsk_version |
Version of the Style Kit used within this theme | 0.3.0 |
- |
Configuration options
Refer to Jekyll's documentation for general information.
Configuration options are used extensively throughout this theme. Some variables are used to set properties such as the brand text or image in the navbar (attributes), others are used to enable various features (feature flags).
Configuration options operate at different scopes, site or page. Site options applies to across a site, whereas page options can be applied to specific content items. Default values can be set for page options, which can then be overridden by specific content items.
Configuration options for this theme are namespaced under a bas_style_kit_jekyll_theme
option - i.e. an option foo
is set as bas_style_kit_jekyll_theme.foo
.
Configuration options in this documentation use a dot notation to indicate a nested structure - i.e. an option foo.bar
should be set as:
foo:
bar
A configuration option bas_style_kit_jekyll_theme.feature_flags.site.back_to_top_anchor
should be set as:
bas_style_kit_jekyll_theme:
feature_flags:
site:
back_to_top_anchor: '[value]'
These config options can be set at a page, collection or site level:
bas_style_kit_jekyll_theme.feature_flags.page.toc
These config options should be changed or set for each website or application:
bas_style_kit_jekyll_theme.attributes.head_title.default
bas_style_kit_jekyll_theme.attributes.head_title.appended
bas_style_kit_jekyll_theme.attributes.head_description
bas_style_kit_jekyll_theme.attributes.site_analytics.id
bas_style_kit_jekyll_theme.attributes.site_brand.text
bas_style_kit_jekyll_theme.attributes.site_development_phase
bas_style_kit_jekyll_theme.attributes.site_feedback_href
bas_style_kit_jekyll_theme.attributes.site_footer.legal_policies.cookies_href
bas_style_kit_jekyll_theme.attributes.site_footer.legal_policies.copyright_href
bas_style_kit_jekyll_theme.attributes.site_footer.legal_policies.privacy_href
These config options may, but don't need to be, changed or set for each website or application:
bas_style_kit_jekyll_theme.attributes.container
bas_style_kit_jekyll_theme.attributes.site_styles
bas_style_kit_jekyll_theme.attributes.site_scripts
bas_style_kit_jekyll_theme.attributes.head_favicon
bas_style_kit_jekyll_theme.attributes.site_brand.img
bas_style_kit_jekyll_theme.attributes.site_brand.href
These config options do not normally, and should not, need to be changed or set:
bas_style_kit_jekyll_theme.attributes.site_back_to_top_target_href
bas_style_kit_jekyll_theme.attributes.site_footer.ogl.href
bas_style_kit_jekyll_theme.attributes.site_footer.ogl.version
These config options must not be changed and should be treated as read only:
site.data.bas-style-kit.bsk-vars.theme_version
site.data.bas-style-kit.bsk-vars.bsk_version
Config Option | Value Type | Allowed Values | Default Value | Notes |
---|---|---|---|---|
bas_style_kit_jekyll_theme.feature_flags.page.toc |
Boolean |
true / false
|
true |
Whether to show the table of contents in standard pages |
bas_style_kit_jekyll_theme.attributes.head_title.default |
String | Any string | 'site title' | Typically 1-3 words |
bas_style_kit_jekyll_theme.attributes.head_title.appended |
String | Any string | None | Typically 1-3 words |
bas_style_kit_jekyll_theme.attributes.head_description |
String | Any string | 'site description' | Typically 1-2 sentences |
bas_style_kit_jekyll_theme.attributes.site_analytics.id |
String | Google Analytics property ID | None | See Site analytics |
bas_style_kit_jekyll_theme.attributes.site_brand.text |
String | Any string | 'site title' | Typically 1-3 words |
bas_style_kit_jekyll_theme.attributes.site_development_phase |
String |
discovery / alpha / beta / live / live-stable / retired / experimental / custom
|
'alpha' | See Site development phase |
bas_style_kit_jekyll_theme.attributes.site_feedback_href |
String | URL to feedback page or other content (e.g. model overlay) | '/feedback.html' | - |
bas_style_kit_jekyll_theme.attributes.site_footer.legal_policies.cookies_href |
String | URL to cookies legal policy | '/legal/cookies' | - |
bas_style_kit_jekyll_theme.attributes.site_footer.legal_policies.copyright_href |
String | URL to copyright legal policy | '/legal/copyright' | - |
bas_style_kit_jekyll_theme.attributes.site_footer.legal_policies.privacy_href |
String | URL to privacy legal policy | '/legal/privacy' | - |
bas_style_kit_jekyll_theme.attributes.container |
String |
fixed / fluid
|
'fixed' | - |
bas_style_kit_jekyll_theme.attributes.site_styles |
Array | Site style object | Empty array | See Using custom CSS/JS |
bas_style_kit_jekyll_theme.attributes.site_scripts |
Array | Site script object | Empty array | See Using custom CSS/JS |
bas_style_kit_jekyll_theme.attributes.head_favicon |
String | default |
'default' | The favicon to use, use 'default' the standard BAS favicon |
bas_style_kit_jekyll_theme.attributes.site_brand.img |
String | URL to image | None | See Navigation menu branding |
bas_style_kit_jekyll_theme.attributes.site_brand.href |
String | URL to content | '/' | See Navigation menu branding |
bas_style_kit_jekyll_theme.attributes.site_back_to_top_target_href |
String | CSS ID selector | '#site-top' | - |
bas_style_kit_jekyll_theme.attributes.site_footer.ogl.href |
String | URL to OGL information page | As implemented | - |
bas_style_kit_jekyll_theme.attributes.site_footer.ogl.version |
String | Any OGL version | As implemented | - |
site.data.bas-style-kit.bsk-vars.theme_version |
String | Any SemVer value | As implemented | - |
site.data.bas-style-kit.bsk-vars.bsk_version |
String | Any BAS Style Kit version | As implemented | - |
Plugins
This theme depends on these plugins:
- Jekyll data - for including theme data files into a site's configuration
- Jekyll menus - for managing navigation menus
- Jekyll tidy - for rewriting HTML output to be well structured
Note: A patched version of the Jekyll menus plugin is used to fix a Ruby 3.0 incompatibility.
Development
Git, Docker and Docker Compose are required to build this project locally.
To update the Docker image for this project, access to the private BAS Docker Registry [1] is also required.
$ git clone https://gitlab.data.bas.ac.uk/web-apps/bsk/bas-style-kit-jekyll-theme.git
$ cd bas-style-kit-jekyll-theme
$ docker-compose up
Visit localhost:9000 to see a preview of the theme.
Note: If you don't have access to the BAS Private Docker Registry, you will need to build the project Docker image
locally first using docker-compose build
.
[1] The first time you use this registry, you will need to authenticate using:
$ docker login docker-registry.data.bas.ac.uk
Updating dependencies
If the .gemspec
for this project is changed, the project Docker image will need to be rebuilt and pushed to the
private BAS Docker Repository [1].
$ docker-compose build app
$ docker-compose push app
[1] The first time you use this registry, you will need to authenticate using:
$ docker login docker-registry.data.bas.ac.uk
Jekyll plugins
Additional Jekyll plugins (gems) can be used by listing them as dependencies in the gems
option in _config.yml
.
They will be installed automatically when this theme is used by an end-user.
Jekyll config options
The Jekyll Data plugin is used to set config options within sites that use this theme. Make sure to document which config options are set by this theme.
Ruby Gem
This theme is distributed as a Ruby Gem, through the public Ruby Gems gem hosting service.
The jekyll-theme-bas-style-kit.gemspec
file details the properties of the Gem for this project.
Note: The spec.files
parameter controls which files in this project are copied into the Gem. If a file is not
listed it won't be included. This is separate to the Git .gitignore
file.
GitHub mirror
A read-only mirror of this project's repository is maintained on GitHub, to support Jekyll's automatic theme installation, and to allow use by those outside of BAS.
Merge requests WILL NOT be accepted on this mirror.
Release procedures
Before release:
- create a release branch
- build and push the app docker image [1]
- if new config options have been set, update the usage section
- update screen-shot (width: 900px)
- close release in changelog
- commit changes, merge with master and tag with new version
- push the release to Ruby Gems [2]
Note: If the BAS Style Kit version changes, make sure to bump that version in _data/bsk_jekyll_vars.json
too.
After release:
- bump the version in:
jekyll-theme-bas-style-kit.gemspec
_data/bas-style-kit/bsk-vars.yml
- build and push the app docker image [1]
- commit changes, merge with master and close release branch
[1]
$ docker-compose build
$ docker-compose push
[2]
$ docker-compose run --entrypoint="" app ash
$ gem build jekyll-theme-bas-style-kit.gemspec
$ gem push jekyll-theme-bas-style-kit-*.gem
Issue tracking
This project uses issue tracking to manage development of new features/improvements and reporting bugs.
Feedback
The maintainer of this project is the BAS Web & Applications Team, they can be contacted through the BAS Service Desk.
License
© UK Research and Innovation (UKRI), 2017-2021, British Antarctic Survey.
You may use and re-use this software and associated documentation files free of charge in any format or medium, under the terms of the Open Government Licence v3.0.
You may obtain a copy of the Open Government Licence at http://www.nationalarchives.gov.uk/doc/open-government-licence/