jekyll-theme-bas-style-kit 0.6.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54c4be6b3f545080f6b9a1732d0cb9ed6df145bd1e12bfd3bed99bd5d5d087f8
-  data.tar.gz: a499c53f7ce5ae7eddf776c21abf72ccad53ac450d4b8898b6051e5e3056a7dd
+  metadata.gz: 857666e665b0c111fc76c3cc8e6fb6fe31901026d2cb3ca3934a43a3fa489040
+  data.tar.gz: 6fd109b6a4ade7f9eb8a3b6c92df36999683a5130603f30164f1e8b1309d3fd5
 SHA512:
-  metadata.gz: 6b5fb5a4c2bff1760efb1e2add4f834d56cb2c0c558fff58b83e4ee9d99dbdfa08b10af8709cf541d2488058f085261f6d198604c0f6c0bd1d71187b94fa16fa
-  data.tar.gz: 67a8d3c47dde8f49ce089d0345da5a59cccb92cb314422c6c8ca35522af85393919493681c13e127737843490bb43f7ae3e421cadca6d580e87345aaaa3fa1e5
+  metadata.gz: a8ff20ced3b6ff5f97266d91fe546108ed8c8a4918031285384515c61da8c4687107751a18881a6c87230fbcd0e425c61ca02ab41711b0fa1fc5f8c5e54b5e01
+  data.tar.gz: 529f1b50ecbcdd7b56a0cdb224a934d5a3ec8618f7ef312f02252767f2663578d28fb6e17bb89d3b571c68f8d30e2fa817945765d57082f2a3885bfcbe89cbae

data/CHANGELOG.md

@@ -5,13 +5,94 @@ This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html
 
 ## [Unreleased][unreleased]
 
+## 0.11.0 - 2021-03-17
+
+### Added
+
+* Updated to Style Kit 0.6.1
+* Updated to jQuery 3.6.0
+* Updated to Jekyll 4.2
+* Updated Ruby dependencies
+* Added optional item type header pattern integration into standard page layout
+
+### Removed
+
+* Synk testing due to incompatibility with modern bundler versions
+
+## 0.10.0 - 2020-06-27
+
+### Added
+
+* Updated to Style Kit 0.6.0-beta
+* Updated to JS Cookie 2.2.1
+* Updated to jQuery 3.5.1
+* Updated to Jekyll 4.1
+* Updated Ruby dependencies
+* Missing patterns for start and 'sign in' page patterns
+* Support for new component patterns (item type header and ORCID iD)
+
+### Changed
+
+* Feedback links changed to open in a new tab
+* Updated licence dates
+* Updated release procedures
+
+## 0.9.0 - 2019-07-02
+
+### Added
+
+* Updated to Style Kit 0.6.0-alpha
+
+### Fixed
+
+* Updating Gem lock file to fix gem versioning issue
+* Correcting use of deprecated `js-libs` in the BAS CDN
+
+### Changed
+
+* Major refactoring and simplification of README and other documentation
+* Removing versioning from Docker containers
+
+## 0.8.0 - 2018-11-28
+
+### Added
+
+* Updated dependencies for internal Gem test site
+* Updated to Style Kit 0.5.0
+* Tracking Gem lock file within project
+
+## 0.7.0 - 2018-11-24
+
+### Added
+
+* 'Problem with this service' (basic) page pattern variant
+* 'Problem with this service' (contact) page pattern variant
+* 'Problem with this service' (alternative) page pattern variant
+* 'Service unavailable' (contact) page pattern variant
+* 'Service unavailable' (availability) page pattern variant
+* 'Service unavailable' (alternative) page pattern variant
+* 'Service unavailable' (partly closed) page pattern variant
+* 'Service unavailable' (closed) page pattern variant
+* 'Service unavailable' (replaced) page pattern variant
+* Updated to Jekyll 3.8.5 to address security vulnerability
+* Updated to Style Kit 0.5.0-beta
+* Snyk dependency scanning support
+
+### Fixed
+
+* README typo
+
+### Changed
+
+* Improving release procedures
+
 ## 0.6.0 - 2018-09-18
 
 ### Changed [BREAKING!]
 
 * Icon uses replaced with alternatives or removed where not needed due to the removal of Font Awesome
-* Favicon attribute option changed, set `bas_style_kit_jekyll_theme.attributes.head_favicon` to `default` for the Style 
-  Kit favicon, other values will be ignored and no favicon will be set 
+* Favicon attribute option changed, set `bas_style_kit_jekyll_theme.attributes.head_favicon` to `default` for the Style
+  Kit favicon, other values will be ignored and no favicon will be set
 
 ### Added
 
@@ -19,6 +100,7 @@ This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html
 * Implemented Style Kit Favicon
 * Implemented 'page not found' pattern and support for design patterns generally
 * Implemented 'Service unavailable (basic)' pattern
+* Ruby dependencies are now scanned for vulnerabilities using Snyk
 
 ### Changed
 
@@ -79,7 +161,7 @@ This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html
 * Re-licensing project under the Open Government License
 * Upgrading to Jekyll 3.7.2
 * Upgrading to Style Kit 0.3.0
-* Layouts, includes and data files are now in a `bas-style-kit` namespace 
+* Layouts, includes and data files are now in a `bas-style-kit` namespace
 * Generic *blank* and *HTML* layouts and associated includes have been redeveloped
 * The Style Kit layout has been split into *base* and *standard* layouts
 * Style Kit includes have been redeveloped and renamed

data/LICENSE.md

@@ -1,8 +1,8 @@
 # License
 
-© UK Research and Innovation (UKRI), 2017-2018, British Antarctic Survey.
+© 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 
+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/

data/README.md

@@ -1,6 +1,6 @@
 # BAS Style Kit Jekyll Theme
 
-Jekyll theme for the [BAS Style Kit](https://stlye-kit.web.bas.ac.uk).
+Jekyll theme for the [BAS Style Kit](https://style-kit.web.bas.ac.uk).
 
 ![Screenshot of theme](screenshot.png)
 
@@ -36,27 +36,9 @@ Refer to [Jekyll's theme documentation](https://jekyllrb.com/docs/themes/) for g
 
 ### Quick start
 
-#### Standard page
-
-To base all pages on the `bsk--standard` layout, add the following to your `_config.yml` file:
+Add these lines to your `_config.yml` file:
 
 ```yml
-# Content settings
-#
-
-
-defaults:
-  -
-    scope:
-      # An empty string here means all files in the project
-      path: ""
-    values:
-      layout: "bas-style-kit/bsk--standard"
-
-
-# Theme settings
-#
-
 bas_style_kit_jekyll_theme:
   attributes:
     head_title:
@@ -67,171 +49,482 @@ bas_style_kit_jekyll_theme:
         text: 'Example service'
         href: '/'
     site_development_phase: 'beta'
-    # Optional - web analytics
-    site_analytics:
-      id: UA-64130716-27
+    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:
+
+```yml
+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](#page-patterns), create a view
+(e.g. `views/error.pug`) with the following:
+
+```html
+---
+layout: views/bas-style-kit/[page-pattern]
+---
+```
+
+Where `[page-pattern]` in the extends value is the name of a page pattern, for example:
+
+```html
+---
+layout: views/bas-style-kit/bsk--page-not-found
+---
+```
+
+#### Use a component pattern
+
+To include a [component pattern](#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
 
-Design patterns are used to demonstrate preferred ways to pass on information to users, or ask them for information.
-For example, information to show when a service is unavailable, formatting dates consistently or asking users for their
-username in a consistent way. See the [Style Kit documentation](https://style-kit.web.bas.ac.uk/patterns) for more 
-information.
+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](https://style-kit.web.bas.ac.uk/patterns) for more information.
 
-These patterns are implemented by this theme based on the reference examples included in the Style Kit. These 
-include patterns for:
+There are two types of pattern used in the Style Kit and these templates:
 
-* **pages** - standalone pages designed to be used without customisation, defined as [Views](#views)
+* [pages](#page-patterns) - standalone pages designed to be used without customisation using [Views](#views)
+* [components](#component-patterns) - inline elements designed to be used without customisation using
+  [Includes](#includes)
 
-### Using custom CSS/JS
+#### Page patterns
 
-...
+These template include [Views](#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.
 
-### Navigation menu items
+See the [Style Kit documentation](https://style-kit.web.bas.ac.uk) for general information on using these patterns.
 
-...
+##### 'page not found' pattern
 
-### Navigation branding
+No configuration options.
 
-...
+##### 'service unavailable' pattern
 
-### Site development phase
+Use page content for:
 
-...
+* contact information
 
-### Website analytics
+Optionally, use page content for:
 
-...
+* details of alternative services
 
-### Views
+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](https://style-kit.web.bas.ac.uk/core/icons/#font-awesome) to show the ORCID symbol.
+
+[1]
 
-Views provide complete pages to implement page [Patterns](#patterns).
+```html
+<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>
+```
 
-All views use the `.html` extension. I.e. the view `page-not-found` should be referenced as `page-not-found.html`.
+[2]
 
-All views are namespaced using a `bas-style-kit/` directory - i.e. the view `page-not-found.html` should be referenced 
-as `bas-style-kit/page-not-found.html`.
+```html
+<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>
+```
 
-Within Jekyll views are implemented as layouts. To implement a view create a page with the relevant 'view layout.
+[3]
+
+```html
+<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]
+
+```html
+<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]
+
+```html
+<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]
+
+```html
 ---
-layout: views/bas-style-kit/page-not-found
+layout: views/bas-style-kit/bsk--sign-in-microsoft
+
+call_to_action_href: #
 ---
 ```
 
-**Note:** You do not need to add any page content.
+#### Component patterns
 
-### Layouts
+These templates use includes for all component patterns. Include parameters are used for customising each instance of
+the component.
 
-This theme defines two types of layout:
+See the [Style Kit documentation](https://style-kit.web.bas.ac.uk) for general information on using these patterns.
 
-* *generic* - non Style Kit specific intended for atypical content
-* *non-generic* - implement the Style Kit either broadly or in more opinionated forms
+##### Item type header pattern
 
-All layouts use the `.html` extension. I.e. the layout `blank` should be referenced as `blank.html`.
+Parameters:
 
-All layouts are namespaced using a `bas-style-kit/` directory - i.e. the layout `blank.html` should be referenced as
-`bas-style-kit/blank.html`.
+* `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
 
-#### Generic layouts
+```html
+{% include bas-style-kit/bsk--pattern--item-type-header.html item_type="Item type" item_title="Item title" %}
+```
 
-* [`blank`](/docs/layout/blank.md)
-* [`html`](/docs/layout/html.md)
+##### ORCID iD pattern
 
-#### Style Kit specific layouts
+Parameters:
 
-* [`bsk--base`](/docs/layout/bsk--base.md)
-* [`bsk--standard`](/docs/layout/bsk--standard.md)
-* [`bsk--standard-page`](/docs/layout/bsk--standard-page.md)
+* `orcid_id` the ORCID iD of an individual as a URL
 
-**Note:** The `bsk--stardard-page` layout is only available in this theme.
+```
+{% include bas-style-kit/bsk--pattern--orcid-id.html orcid_id="https://sandbox.orcid.org/0000-0001-8373-6934" %}
+```
 
-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.
+**Note:** If not already included via a layout, include
+[Font Awesome](https://style-kit.web.bas.ac.uk/core/icons/#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:
+
+```yml
+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)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) 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)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) support with a
+hard-coded, `anonymous`, value.
+
+### Navigation menu items
+
+When using the `bsk--standard.html` layout, a [navbar](https://style-kit.web.bas.ac.uk/components/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](#navigation-branding)
+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](https://www.bas.ac.uk) and the [BAS data catalogue](https://data.bas.ac.uk).
+Other websites and applications can be added as well where relevant.
+
+The primary and secondary navigation menu's support:
+
+* [navbar items](https://style-kit.web.bas.ac.uk/components/navbar/#item)
+* [navbar drop-down menus](https://style-kit.web.bas.ac.uk/components/navbar/#drop-down-menus)
+* [navbar drop-down menu items](https://style-kit.web.bas.ac.uk/components/navbar/#drop-down-menus)
+
+The navigation launcher menu, which is implemented as a drop-down menu, supports:
+
+* [navbar drop-down menu items](https://style-kit.web.bas.ac.uk/components/navbar/#drop-down-menus)
+
+All navigation menus are implemented using the [Jekyll menus](https://github.com/forestryio/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](https://style-kit.web.bas.ac.uk/components/navbar/) 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](https://style-kit.web.bas.ac.uk/components/navbar/#brand-text) - set using the
+`bas_style_kit_jekyll_theme.attributes.site_brand.text` config variable
+* [brand image](https://style-kit.web.bas.ac.uk/components/navbar/#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](https://style-kit.web.bas.ac.uk/core/colours/#development-phase-colours).
+
+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:
 
+```yml
+bas_style_kit_jekyll_theme:
+  attributes:
+    site_development_phase: 'alpha'
 ```
----
-layout: bas-style-kit/bsk--standard
-main_content_classes: bsk-pattern-page-not-found
----
 
-<h1 class="bsk-page-header">Page not found</h1>
+#### 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:
+
+```yml
+bas_style_kit_jekyll_theme:
+  attributes:
+    site_development_phase: 'experimental'
 ```
 
-### Includes
+### Website analytics
 
-Refer to [Jekyll's documentation](https://jekyllrb.com/docs/include/) for general information.
+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.
 
-This theme uses includes extensively to give fine grained control over how elements such as the navbar behave, including
-both their content and structure.
+**Note:** When used, the anonymise IP option in Google Analytics is enabled by default.
 
-Includes are often used conditionally using a related configuration option, to be disabled more easily.
+For example:
+
+```yml
+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](#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
+---
+```
 
-All includes use the `.html` extension. I.e. the include `body` should be referenced as `body.html`.
+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](#page-patterns) section for more information.
 
-All includes are namespaced using a `bas-style-kit/` directory - i.e. the include `body.html` should be referenced as
-`bas-style-kit/body.html`.
+### Layouts
 
-#### Generic includes
+Refer to [Jekyll's documentation](https://jekyllrb.com/docs/layouts/) for general information.
 
-* [`head`](/docs/include/head.md)
-* [`body`](/docs/include/body.md)
-* [`toc`](/docs/include/toc.md)
+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:
 
-#### Style Kit specific includes
+* `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
 
-* [`bsk-head`](/docs/include/bsk-head.md)
-* [`bsk-body`](/docs/include/bsk-body.md)
-* [`bsk-body--standard`](/docs/include/bsk-body--standard.md)
+For example:
 
-HTML Head includes:
+```markdown
+---
+layout: bas-style-kit/html
+---
 
-* [`bsk-head--core-meta`](/docs/include/bsk-head--core-meta.md)
-* [`bsk-head--seo-meta`](/docs/include/bsk-head--seo-meta.md)
-* [`bsk-head--core-styles`](/docs/include/bsk-head--core-styles.md)
-* [`bsk-head--favicon`](/docs/include/bsk-head--favicon.md)
+Page content
+```
 
-HTML Body includes:
+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.
 
-* [`bsk-body--core-scripts`](/docs/include/bsk-body--core-scripts.md)
-* [`bsk-body--analytics-script`](/docs/include/bsk-body--analytics-script.md)
-* [`bsk-body--back-to-top`](/docs/include/bsk-body--back-to-top.md)
-* [`bsk-body--standard-header`](/docs/include/bsk-body--standard-header.md)
-* [`bsk-body--standard-footer`](/docs/include/bsk-body--standard-footer.md)
-* [`bsk-body--page-header`](/docs/include/bsk-body--page-header.md)
-* [`bsk-body--toc`](/docs/include/bsk-body--toc.md)
+For example:
 
-Footer includes:
+```markdown
+---
+layout: bas-style-kit/bsk--standard
+main_content_classes: foo
+---
 
-* [`bsk-footer--back-to-top`](/docs/include/bsk-footer--back-to-top.md)
-* [`bsk-footer--contents`](/docs/include/bsk-footer--contents.md)
-* [`bsk-footer--governance`](/docs/include/bsk-footer--governance.md)
-* [`bsk-footer--is-something-wrong`](/docs/include/bsk-footer--is-something-wrong.md)
-* [`bsk-footer--legal-policies`](/docs/include/bsk-footer--legal-policies.md)
+Page content
+```
 
-Header includes:
+### Includes
 
-* [`bsk-header--cookie-notice`](/docs/include/bsk-header--cookie-notice.md)
-* [`bsk-header--site-navigation`](/docs/include/bsk-header--site-navigation.md)
-* [`bsk-header--development-phase`](/docs/include/bsk-header--development-phase.md)
+Refer to [Jekyll's documentation](https://jekyllrb.com/docs/includes/) for general information.
 
-Navigation includes:
+This theme uses includes extensively to give fine grained control over how elements such as the navbar behave, including
+both their content and structure.
 
-* [`bsk-nav--header`](/docs/include/bsk-nav--header.md)
-* [`bsk-nav--collapse`](/docs/include/bsk-nav--collapse.md)
-* [`bsk-nav-header--collapse-trigger`](/docs/include/bsk-nav-header--collapse-trigger.md)
-* [`bsk-nav-header--brand`](/docs/include/bsk-nav-header--brand.md)
-* [`bsk-nav-collapse--primary-navigation`](/docs/include/bsk-nav-collapse--primary-navigation.md)
-* [`bsk-nav-collapse--secondary-navigation`](/docs/include/bsk-nav-collapse--secondary-navigation.md)
+Includes are often used conditionally using a related configuration option, to be disabled more easily.
 
 ### Data files
 
@@ -239,15 +532,9 @@ Refer to [Jekyll's documentation](https://jekyllrb.com/docs/datafiles/) for gene
 
 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 
+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`.
 
-#### Style Kit specific data files
-
-* [bsk-css](/data-file/bsk-css.md)
-* [bsk-js](/data-file/bsk-js.md)
-* [bsk-vars](/data-file/bsk-vars.md)
-
 ### Variables
 
 Refer to [Jekyll's documentation](https://jekyllrb.com/docs/variables/) for general information.
@@ -266,7 +553,7 @@ Refer to [Jekyll's documentation](https://jekyllrb.com/docs/configuration/) for
 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 
+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.
 
@@ -290,25 +577,84 @@ bas_style_kit_jekyll_theme:
       back_to_top_anchor: '[value]'
 ```
 
-#### Style Kit specific configuration options
-
-* [feature flags](/docs/config/feature-flags.md)
-* [attributes](/docs/config/attributes.md)
+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](#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](#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](#using-custom-cssjs)             |
+| `bas_style_kit_jekyll_theme.attributes.site_scripts`                              | Array      | Site script object                                                                              | *Empty array*      | See [Using custom CSS/JS](#using-custom-cssjs)             |
+| `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](#navigation-menu-branding)  |
+| `bas_style_kit_jekyll_theme.attributes.site_brand.href`                           | String     | URL to content                                                                                  | '/'                | See [Navigation menu branding](#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](https://semver.org/) 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](https://github.com/ashmaroli/jekyll-data) - for including theme data files into a site's configuration
-* [Jekyll menu](https://github.com/forestryio/jekyll-menus) - for managing navigation menus
+* [Jekyll menus](https://github.com/forestryio/jekyll-menus) - for managing navigation menus
 * [Jekyll tidy](https://github.com/apsislabs/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](https://git-scm.com), [Docker](https://www.docker.com/community-edition) and 
+[Git](https://git-scm.com), [Docker](https://www.docker.com/community-edition) and
 [Docker Compose](https://docs.docker.com/compose/overview/) are required to build this project locally.
 
-To update the Docker image for this project, access to the private 
+To update the Docker image for this project, access to the private
 [BAS Docker Registry](https://docker-registry.data.bas.ac.uk) [1] is also required.
 
 ```shell
@@ -319,7 +665,7 @@ $ docker-compose up
 
 Visit [localhost:9000](http://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 
+**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:
@@ -330,7 +676,7 @@ $ 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 
+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].
 
 ```shell
@@ -352,7 +698,7 @@ 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 
+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
@@ -361,12 +707,12 @@ This theme is distributed as a Ruby Gem, through the public [Ruby Gems](https://
 
 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 
+**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 
+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.
@@ -376,11 +722,7 @@ Merge requests **WILL NOT** be accepted on this mirror.
 Before release:
 
 1. create a release branch
-2. remove `-develop` from the version in:
-  * `jekyll-theme-bas-style-kit.gemspec`
-  * `docker-compose.yml`
-  * `_data/bsk_jekyll_vars.json`
-3. push the app docker image [1]
+3. build and push the app docker image [1]
 4. if new config options have been set, update the usage section
 5. update screen-shot (width: 900px)
 6. close release in changelog
@@ -391,11 +733,10 @@ Before release:
 
 After release:
 
-1. bump the version with `-develop` as a prefix in:
+1. bump the version in:
   * `jekyll-theme-bas-style-kit.gemspec`
-  * `docker-compose.yml`
   * `_data/bsk_jekyll_vars.json`
-2. push the app docker image [1]
+2. build and push the app docker image [1]
 3. commit changes, merge with master and close release branch
 
 [1]
@@ -408,28 +749,26 @@ $ docker-compose push
 [2]
 
 ```shell
-$ docker-compose run --entrypoint=[] app ash
+$ 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](https://trello.com/b/0Mhzizpk/bas-style-kit) to manage development of new 
+This project uses [issue tracking](https://trello.com/b/0Mhzizpk/bas-style-kit) to manage development of new
 features/improvements and reporting bugs.
 
-**Note:** Read & write access to this issue tracker is restricted. Contact the project maintainer to request access.
-
 ## Feedback
 
-The maintainer of this project is the BAS Web & Applications Team, they can be contacted through the 
+The maintainer of this project is the BAS Web & Applications Team, they can be contacted through the
 [BAS Service Desk](mailto:servicedesk@bas.ac.uk).
 
 ## License
 
-© UK Research and Innovation (UKRI), 2017-2018, British Antarctic Survey.
+© 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 
+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/