BAS Style Kit Jekyll Theme

Jekyll theme for the BAS Style Kit.

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:

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:

Optionally, use page content for:

Optionally, use a pattern_availability page variable for setting the availability line:

'problem with this service' pattern

Use page content for:

Optionally, use page content for:

'start' pattern

Use page content for:

Optionally, use page content for:

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:

---
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:

{% include bas-style-kit/bsk--pattern--item-type-header.html item_type="Item type" item_title="Item title" %}
ORCID iD pattern

Parameters:

{% 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.

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):

  1. a primary navigation menu - aligned left, after brand elements

  2. a secondary navigation menu - aligned right, before the launcher menu

  3. 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.

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 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.htmllayout, 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:

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:

These config options should be changed or set for each website or application:

These config options may, but don't need to be, changed or set for each website or application:

These config options do not normally, and should not, need to be changed or set:

These config options must not be changed and should be treated as read only:

| 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:

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:

  1. create a release branch

  2. build and push the app docker image [1]

  3. if new config options have been set, update the usage section

  4. update screen-shot (width: 900px)

  5. close release in changelog

  6. commit changes, merge with master and tag with new version

  7. 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:

  1. bump the version in:

  2. jekyll-theme-bas-style-kit.gemspec

  3. _data/bsk_jekyll_vars.json

  4. build and push the app docker image [1]

  5. 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 www.nationalarchives.gov.uk/doc/open-government-licence/