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.

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

Refer to Jekyll's theme documentation for general information.

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

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"

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

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

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.

No configuration options.

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

Use page content for:

• contact information

Optionally, use page content for:

• details of alternative services

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>

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

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.

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" %}

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.

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 have the following properties:

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.

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:

• navbar items
• navbar drop-down menus
• navbar drop-down menu items

The navigation launcher menu, which is implemented as a drop-down menu, supports:

• navbar drop-down menu items

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.

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. /).

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'

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'

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

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

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.

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.

Refer to Jekyll's documentation for general information.

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

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.

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

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

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.

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.

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.

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.

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:

• jekyll-theme-bas-style-kit.gemspec
• _data/bas-style-kit/bsk-vars.yml

2. build and push the app docker image [1]
3. 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

This project uses issue tracking to manage development of new features/improvements and reporting bugs.

The maintainer of this project is the BAS Web & Applications Team, they can be contacted through the BAS Service Desk.

© 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/