jekyll-theme-bas-style-kit 0.5.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89c327ba8fda0366d129d83bf7377e02520027cdf14f228d5cbb0b0526d0041c
-  data.tar.gz: 3ebf7581bb4114d223c746711e762150c6f5309ee981c21520d5869e23a50f79
+  metadata.gz: b908438db459e82826393134d985468e10310620aa50ad9aa64a37ea3f2315d3
+  data.tar.gz: 0a0cf92ed57a4d435fc80edc4e967d76517b4c1c070952a3af97dc443bb097ed
 SHA512:
-  metadata.gz: 11477eb8b9156a57d3f7c15f077e99bba66294d5eb62ceb0062ef1dfa5fc1d44c50071e1a608d2588ca1c4be748abcbcc2e537c6642a510b0982d843e9cdf11a
-  data.tar.gz: 48826acebfe2ad7a89895838897d368913115b7f53a1f48a2b65b6f105d5e49fb7db679ae8afcc2370e92dd9caaf5a5a2c6666feba258d65ad542197d63188a8
+  metadata.gz: 6798c1642676febbb0a84bc8cc86737252bdcb802707fa8a568152f72860a43732d4c89e9f09233d5c5169ebbbb59d35a6ac696e4eb6b642cbef9d0f206ce44c
+  data.tar.gz: 8802655c6262bc25076cda5fc0c4a3064ed64b82dc331bf9585337940bae59ae139c8f92d2e2d6273f27c3f14c0da5ee722d5ddf5862812fe357140b43456964

data/CHANGELOG.md

@@ -5,6 +5,103 @@ This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html
 
 ## [Unreleased][unreleased]
 
+### 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
+
+### Added
+
+* Updated to Style Kit 0.5.0-alpha
+* 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
+
+* Updating order of navigation launcher items
+* Improving Dockerfiles
+* Improving internal test content
+
+### Fixed
+
+* Corrected link to issue tracker
+
 ## 0.5.0 - 2018-07-06
 
 ### Fixed
@@ -54,7 +151,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-2020, 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)
 
@@ -20,11 +20,11 @@ $ bundle
 
 Or install it yourself as:
 
-```
+```shell
 $ gem install jekyll-theme-bas-style-kit
 ```
 
-Add these lines to your `_config.yml` to use the Style Kit theme:
+Finally, to use the theme, add this line to your `_config.yml` file:
 
 ```yaml
 theme: jekyll-theme-bas-style-kit
@@ -34,106 +34,497 @@ theme: jekyll-theme-bas-style-kit
 
 Refer to [Jekyll's theme documentation](https://jekyllrb.com/docs/themes/) for general information.
 
-### Layouts
+### Quick start
 
-This theme defines two types of layout:
+Add these lines to your `_config.yml` file:
 
-* *generic* - non Style Kit specific intended for atypical content
-* *non-generic* - implement the Style Kit either broadly or in more opinionated forms
+```yml
+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'
+```
 
-All layouts use the `.html` extension. I.e. the layout `blank` should be referenced as `blank.html`.
+To optionally add navigation menu items, add these lines to `_data/menus.yml`:
 
-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`.
+```
+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 use a layout by default add the following to your `_config.yml`:
+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
+      # An empty string here means all files in the project
       path: ""
     values:
-      layout: "bas-style-kit/bsk--standard"
+      layout: "app"
 ```
 
-#### Generic layouts
+#### Use a page pattern
 
-* [`blank`](/docs/layout/blank.md)
-* [`html`](/docs/layout/html.md)
+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:
 
-#### Style Kit specific layouts
+```html
+---
+layout: views/bas-style-kit/[page-pattern]
+---
+```
 
-* [`bsk--base`](/docs/layout/bsk--base.md)
-* [`bsk--standard`](/docs/layout/bsk--standard.md)
-* [`bsk--standard-page`](/docs/layout/bsk--standard-page.md)
+Where `[page-pattern]` in the extends value is the name of a page pattern, for example:
 
-### Includes
+```html
+---
+layout: views/bas-style-kit/bsk--page-not-found
+---
+```
 
-Refer to [Jekyll's documentation](https://jekyllrb.com/docs/include/) for general information.
+#### Use a component pattern
 
-This theme uses includes extensively to give fine grained control over how elements such as the navbar behave, including
-both their content and structure.
+To include a [component pattern](#component-pattern), call the relevant include with an required parameters.
+For example:
 
-Includes are often used conditionally using a related configuration option, to be disabled more easily.
+```
+{% include bas-style-kit/bsk--pattern--item-type-header.html item_type="Item type" item_title="Item title" %}
+```
 
-All includes use the `.html` extension. I.e. the include `body` should be referenced as `body.html`.
+### Patterns
 
-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`.
+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.
 
-#### Generic includes
+There are two types of pattern used in the Style Kit and these templates:
 
-* [`head`](/docs/include/head.md)
-* [`body`](/docs/include/body.md)
-* [`toc`](/docs/include/toc.md)
+* [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)
 
-#### Style Kit specific includes
+#### Page patterns
 
-* [`bsk-head`](/docs/include/bsk-head.md)
-* [`bsk-body`](/docs/include/bsk-body.md)
-* [`bsk-body--standard`](/docs/include/bsk-body--standard.md)
+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.
 
-HTML Head includes:
+See the [Style Kit documentation](https://style-kit.web.bas.ac.uk) for general information on using these patterns.
 
-* [`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 not found' pattern
 
-HTML Body includes:
+No configuration options.
 
-* [`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)
+##### 'service unavailable' pattern
 
-Footer includes:
+Use page content for:
 
-* [`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)
+* 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](https://style-kit.web.bas.ac.uk/core/icons/#font-awesome) to show the ORCID symbol.
+
+[1]
+
+```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>
+```
+
+[2]
+
+```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>
+```
+
+[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/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](https://style-kit.web.bas.ac.uk) 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
+
+```html
+{% 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](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'
+```
 
-Header includes:
+#### Resource objects
 
-* [`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)
+Resource objects have the following properties:
 
-Navigation includes:
+| 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=`  |
 
-* [`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)
+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'
+```
+
+#### 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'
+```
+
+### 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:
+
+```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
+---
+```
+
+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.
+
+### Layouts
+
+Refer to [Jekyll's documentation](https://jekyllrb.com/docs/layouts/) 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:
+
+```markdown
+---
+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:
+
+```markdown
+---
+layout: bas-style-kit/bsk--standard
+main_content_classes: foo
+---
+
+Page content
+```
+
+### Includes
+
+Refer to [Jekyll's documentation](https://jekyllrb.com/docs/includes/) 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
 
@@ -141,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.
@@ -168,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.
 
@@ -192,10 +577,67 @@ 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
 
@@ -207,10 +649,10 @@ This theme depends on these plugins:
 
 ## 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
@@ -221,7 +663,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:
@@ -232,7 +674,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
@@ -254,7 +696,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
@@ -263,12 +705,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.
@@ -278,11 +720,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
@@ -293,11 +731,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]
@@ -310,31 +747,26 @@ $ docker-compose push
 [2]
 
 ```shell
-# add 'entrypoint: ash' to the app service in /docker-compose.yml
-$ docker-compose run app gem build jekyll-theme-bas-style-kit.gemspec
-$ docker-compose run app gem push jekyll-theme-bas-style-kit-*.gem
-# remove 'entrypoint: ash' from the app service in /docker-compose.yml
+$ docker-compose run --entrypoint="" app ash
+$ gem build jekyll-theme-bas-style-kit.gemspec
+$ gem push jekyll-theme-bas-style-kit-*.gem
 ```
 
-**Note:** Add `entrypoint: ash` to the `app` service in `docker-compose.yml` to run these commands
-
 ## Issue tracking
 
-This project uses [issue tracking](https://gitlab.data.bas.ac.uk/web-apps/bsk/bas-style-kit-jekyll-theme) 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.
+This project uses [issue tracking](https://trello.com/b/0Mhzizpk/bas-style-kit) 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 
+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-2020, 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/