jekyll-theme-bas-style-kit 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d76c808d94ebc8040f64c706f511098847b961b7
-  data.tar.gz: 4874064a8bae4db2cbfdb105e2d55cc06153c83d
+  metadata.gz: a56cc128c5a45c3cc09c6aa8302f3637e7ebad32
+  data.tar.gz: 235c350940d5acc5a81ce529535004a754e1b148
 SHA512:
-  metadata.gz: 0893c1845dc61fec2fcafa12fa9f6bbe8dad5ac9dd679223eaaae0495de5cb7ff426a3702e10a4ef434b3928dd391005c53a417db0b00d55633918dd742c21e8
-  data.tar.gz: 0debd3d55267dcedf2a5082b80e096da90e1127dad0d37b5d22b4e55394b48ca3770fdb2b0296b587475358f5c7b74d63ec7876271f675d1c3d870c01748ac0e
+  metadata.gz: 6c9df02310e8cd1646246a0a865ba28127883bffa7abde5a0523bbc45488279033255ccbfb3ce91fa29e83aedd9fc9354972fbbb0d1c9a3c0e814a97661674a5
+  data.tar.gz: 4379eacbf303c3ac5057fd239c4b0bf9df2b586b3910ccbc8fe26ed90a2ac12200f710a3b89bfb7b8c30a78bb1af53046710361425b8884c5c2593993b0761e5

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# BAS Style Kit Jekyll Theme - Change log
+
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased][unreleased]
+
+## 0.1.0 - 12/03/2017
+
+### Added
+
+* Initial project - based on BAS Style Kit version 0.1.0, and adapted from the BAS Style Kit documentation Jekyll site

data/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing policy
+
+We welcome contributions from both other NERC centres and from external entities under the following guidelines:
+
+* These are general guidelines used by default for projects that we make available, 
+they do not represent any formal policy or notice
+
+* The preferred method of integrating contributions is through a Git pull request to the nominated repository
+
+* The preferred method of raising issues is through the nominated issue tracker
+
+* Follow any defined coding standards where specified, or any obvious conventions implied within the code
+
+Last updated: February 2016
+Contact address: webapps@bas.ac.uk (BAS Web & Applications Team)

data/LICENSE-MIT.md

@@ -0,0 +1,21 @@
+The MIT license
+
+Copyright (c) NERC BAS 2017 https://www.bas.ac.uk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/LICENSE.md

@@ -0,0 +1,7 @@
+# License
+
+Copyright 2017 NERC BAS.
+
+Unless stated otherwise all code is licensed under the MIT license.
+
+Copies of this license are included within this project.

data/README.md

@@ -0,0 +1,632 @@
+# jekyll-theme-bas-style-kit
+
+Jekyll theme implementation of the [BAS Style Kit](https://stlye-kit.web.bas.ac.uk).
+
+![Screenshot of theme](screenshot.png)
+
+## Installation
+
+Add this line to your Jekyll site's `Gemfile`:
+
+```ruby
+gem "jekyll-theme-bas-style-kit"
+```
+
+And then execute:
+
+```shell
+$ bundle
+```
+
+Or install it yourself as:
+
+```
+$ gem install jekyll-theme-bas-style-kit
+```
+
+## Usage
+
+Refer to [Jekyll's theme documentation](https://jekyllrb.com/docs/themes/) for general information.
+
+### Selecting the BAS Style Kit Jekyll theme
+
+Add this line to your Jekyll site's `_config.yml`:
+
+```yaml
+theme: jekyll-theme-bas-style-kit
+```
+
+### Layouts
+
+This theme provides three layouts:
+
+* blank
+* HTML
+* default
+
+#### Blank
+
+Returns content without modification, and is used as the fundamental layout, from which all other layouts derive.
+
+This layout is useful if you need to output data in a format other than HTML (such as JSON or XML).
+
+**Note:** You will need to set a suitable content-type header if returning non-HTML content.
+
+#### HTML
+
+Returns content in the `<body>` tag of a basic HTML page. Includes `<head>` elements returned by the *head* include.
+
+**Note:** This layout includes the BAS Style Kit CSS styles, but not Bootstrap JavaScript components (see the 
+*default* layout for this).
+
+**Note:** This layout does not include information about the use of Cookies, which **MUST** be displayed if used on a
+website. You will need to provide a suitable notice to users if this applies. See the *Cookie notice* section for more
+information.
+
+This layout is useful if you need to show content in isolation, or using a specific page style, such as a page designed
+for printing, or for displaying full screen.
+
+#### Default
+
+Returns content in a [container](https://style-kit.web.bas.ac.uk/core/layout/#fixed-width-container) with a number of 
+additional components using includes:
+
+| Component                | Include File                     | Description                                                                                  | Notes                                                                                      |
+| ------------------------ | -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Cookie notice banner     | `layout/cookie-banner.html`      | Dismissible cookie notice                                                                    | See the *Cookie notice* section for more information                                       |
+| Site navigation          | `layout/site-navigation.html`    | [Navbar](https://style-kit.web.bas.ac.uk/components/navbar/) containing site navigation      | See the *Site navigation* section for more information                                     |
+| Development phase banner | `layout/phase-banner.html`       | Contextual warning for current development phase                                             | See the *Development phase* section for more information                                   |
+| Site footer              | `layout/site-footer.html`        | Basic [footer](https://style-kit.web.bas.ac.uk/components/footer/)                           | Designed to be overiden, see the *Legal policies* section for information it must contain |
+| JavaScript               | `snippets/body-js.html`          | Scripts required for jQuery, Bootstrap's JavaScript components, and the cookie notice banner | -                                                                                          |
+| Analytics                | `snippets/google-analytics.html` | Scripts required for Google Analytics                                                        | Not included if `ga_property` config option is not set                                     |
+
+### Includes
+
+Includes for this theme are split into *layout* and *snippets*. Layouts are used as part of the visual structure of the
+site (such as the main navigation). Snippets are more general and used in various places (including in other includes).
+
+#### Cookie Banner
+
+**Type:** Layout
+
+**File:** `layout/cookie-banner.html`
+
+Presents a full-width banner, pinned to the top of the page, with a statement that the site uses cookies, and where a
+user can find out more information.
+
+This banner can be dismissed by the user, which will hide the message for 30 days using (ironically) a cookie.
+
+See the *Cookie notice* section for more information.
+
+**Note:** This include depends on the `snippets/body-js.html` include.
+
+#### Phase Banner
+
+**Type:** Layout
+
+**File:** `layout/phase-banner.html`
+
+Presents a full-width banner, pinned after the site navigation, with a statement describing the status of the website. 
+For example, if a website is in the *beta* phase of development, a notice advising users that the website is still 
+under development will be shown, with an invitation for them to submit feedback.
+
+If a website is in the *live* phase of development, no banner is shown.
+
+See the *Development phase notice* and *Website feedback* sections for more information.
+
+**Note:** The message shown for each development phase cannot currently be changed.
+
+#### Site footer
+
+**Type:** Layout
+
+**File:** `layout/site-footer.html`
+
+Provides a basic [footer](https://style-kit.web.bas.ac.uk/components/footer/) designed to meet requirements for:
+
+* linking to the top of the current page and to give feedback
+* explaining the license for content within the website
+* displaying links to legal polices
+
+As footers will vary greatly between websites, this footer is deliberately basic, and limited, in its structure. It is
+expected this include will be overiden by each website with its own specific footer.
+
+See the *Legal policies* and *Website feedback* sections for information on what a footer **MUST** contain.
+
+#### Site navigation
+
+**Type:** Layout
+
+**File:** `layout/site-navigation.html`
+
+Provides a default implementation of a [navbar](https://style-kit.web.bas.ac.uk/components/navbar/) designed to meet 
+the needs of most websites. The navbar consists of:
+
+* the site title
+* a toggle to show or hide navigation items on smaller devices (such as phones)
+* a set of navigation items (see the *Site navigation* section for how to set these)
+* a drop-down of other relevant BAS websites, including the BAS public website and data catalogue
+* a link to give feedback about the website
+
+See the *Site navigation* and *Website feedback* sections for more information.
+
+#### Back to top
+
+**Type:** Snippet
+
+**File:** `snippets/back-to-top.html`
+
+Provides a link to the `#site-top` anchor, positioned at the top of each page. It is shown in the default footer 
+include.
+
+**Note:** This snippet depends on the *default* layout being used, or a layout with a `#site-top` element defined.
+
+#### Body JS
+
+**Type:** Snippet
+
+**File:** `snippets/body-js.html`
+
+Inserts `<script>` tags for:
+
+* jQuery (required for Bootstrap's JavaScript components and the cookie banner)
+* Bootstrap JavaScript components (required for components such as drop-down menus)
+* JS Cookie (required for the cookie banner)
+* cookie banner (a script to hide the cookie banner using a cookie, if the user chooses to)
+
+**Note:** This snippet is designed for loading JavaScript *after* the main page content. If a script needs to be run 
+before this content, you will need to do this manually.
+
+#### Google Analytics
+
+**Type:** Snippet
+
+**File:** `snippets/google-analytics.html`
+
+If the `ga_property` config option is set, include the Google Analytics tracking script, and configures it for the 
+relevant Google Analytics property.
+
+The tracking script is configured to anonymise the IP address of visitors client side, meaning we it is never visible 
+to the Google Analytics service.
+
+#### Head
+
+**Type:** Snippet
+
+**File:** `snippets/head.html`
+
+Represents the `<head>` tag of a HTML page with these elements:
+
+* HTML doc-type
+* UTF-8 character encoding scheme
+* directive for Internet Explorer to use the latest rendering engine available (ignored by Microsoft Edge)
+* directive for devices to set the viewport width to the width of the current device in CSS pixels at a scale of 100%,
+and an initial scale of 100%
+* the title directive, containing a page title (if set) followed by the site `title` config option
+* the description directive, containing the site `description` config option
+* the canonical directive, used for constructing internal URLs and by search engines for deduplicating content where it
+is available from multiple locations. Uses the `baseurl` config option and expresses a preference for URLs without a
+`.html` extension if used.
+* links to the image used by mobile devices if this website is pinned to a home-screen
+* references to the BAS Style Kit, Jekyll theme, and website specific CSS
+* workarounds for older versions of Internet Explorer to not break with the use of modern HTML features
+
+#### Is something wrong
+
+**Type:** Snippet
+
+**File:** `snippets/is-something-wrong.html`
+
+Displays a link to give feedback about the current website. It is shown in the default footer include.
+
+See the *Website feedback* section for more information.
+
+### Assets
+
+All assets in this theme are scoped to the `bsk-jekyll` directory.
+
+**Note:** In the longer term, all of these assets are due to be hosted within the BAS CDN, rather than within each 
+website that uses this theme. This makes such sites more consistent, and gives performance benefits using browser 
+caching.
+
+#### `bsk-jekyll/bas-style-kit-jekyll-theme.scss`
+
+CSS styles specific to this theme, designed to be the same for each site using this theme.
+
+**Note:** This file **SHOULD NOT** be overiden, use `css/main.scss` instead.
+
+**Note:** This file currently contains some styles that are waiting to be merged with the upstream Style Kit project.
+
+#### `bsk-jekyll/img/apple-touch-icon.png`
+
+Image used if this website is pinned to the start screen of a smartphone.
+
+**Note:** The name of this file is conventional, and **SHOULD NOT** be changed. It **MAY** be overiden if needed.
+
+#### `bsk-jekyll/js/cookie-banner.js`
+
+Simple script to set a cookie when the user dismisses the cookie banner. If this cookie is present the banner will not 
+be shown on subsequent pages for a period of 30 days. After this time the banner will be shown again, until dismissed 
+again for another 30 days.
+
+#### `css/main.scss`
+
+CSS styles specific to each website. This file is empty by default and is designed to be overiden by each website.
+
+**Note:** This file is included in the *head* include, and so **SHOULD NOT** be removed to avoid 404 errors. It **MAY**
+be left empty if not needed.
+
+**Note:** This file will not be moved to the BAS CDN.
+
+### Config options
+
+There are a number of config options used by this theme, which **SHOULD** be set, within `_config.yml`.
+
+Jekyll config options which **SHOULD** be set:
+
+* `title`
+* `description`
+
+Theme specific options which **SHOULD** be set:
+                        
+| Option              | Type   | Description                                                    | Example Value         | Notes                                                                       |
+| ------------------- | ------ | -------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------- |
+| `phase`             | String | Current development phase for website                          | "alpha"               | See the *Development phase notice* section for more information             |
+| `copyright_href`    | String | URL to copyright statement for website                         | "/copyright-statement | See the *Legal policies* section for more information                       |
+| `privacy_href`      | String | URL to privacy policy for website                              | "/privacy-policy"     | See the *Legal policies* section for more information                       |
+| `cookies_href`      | String | URL to cookie policy for website                               | "/cookie-policy"      | See the *Legal policies* section for more information                       |
+| `feedback_href`     | String | URL to feedback page for website                               | "/feedback"           | See the *Website feedback* section for more information                     |
+| `ga_property`       | String | Google Analytics property for website                          | "UA-64130716-XX"      | Values should start with `UA-64130716-` for BAS Google Analytics properties |
+| `nav_items`         | List   | Items in this website to include in the site navigation        | *List of items*       | See the *Site navigation* section for more information                      |
+| `nav_related_sites` | List   | Items for other BAS websites to include in the site navigation | *List of items*       | See the *Site navigation* section for more information                      |
+
+### Site navigation
+
+Two kinds of navigation item are supported within the site navigation (an instance of the  
+[navbar](https://style-kit.web.bas.ac.uk/components/navbar/) component):
+
+1. resources within the current website - shown after the site title
+2. BAS websites relevant to the current website - shown before the feedback item on the navbar's right
+
+Both kinds of item are displayed using the *Site navigation* include, and set using config options:
+
+* internal items: `nav_items`
+* related items: `nav_related_sites`
+
+#### Internal items
+
+This theme allows multiple types of item to be used for internal navigation items. Some of these types are generic, 
+some are included to integrate more easily with Jekyll's conventions and features.
+
+**Properties**
+
+| Property | Type   | Required | Description                                       | Example Value | Notes                                            |
+| -------- | ------ | -------- | ------------------------------------------------- | ------------- | ------------------------------------------------ |
+| `name`   | String | Yes      | Used as the link text                             | `About`       | -                                                |
+| `type`   | String | Yes      | Controls how this item is processed and displayed | `single_item` | May require additional properties to be set      |
+
+Supported item types are:
+
+* `single_item`
+* `dropdown_item`
+
+**Example**
+
+```yml
+nav_items:
+  -
+    name: About
+    type: single_item
+```
+
+##### Single item
+
+The most basic item type, set manually and displayed as a navbar item (link).
+
+**Additional Properties**
+
+| Property | Type   | Required | Description                       | Example Value | Notes                                            |
+| -------- | ------ | -------- | --------------------------------- | ------------- | ------------------------------------------------ |
+| `href`   | String | Yes      | Used as the link `href` attribute | `/about`      | Set the `href` property to `/` for the home page |
+
+**Active item**
+
+When the current page matches the `href` attribute, the item is made the active navbar item.
+
+**Example**
+
+```yml
+nav_items:
+  -
+    name: Home
+    type: single_item
+    href: /
+  -
+    name: About
+    type: single_item
+    href: /about
+```
+
+##### Dropdown item
+
+A more complex item type, set manually and displayed as a 
+[navbar drop-down](https://style-kit.web.bas.ac.uk/components/navbar/#drop-down-menus).
+
+**Note:** Advanced drop-down features such as dividers and headers are not supported.
+
+**Additional Properties**
+
+| Property           | Type   | Required | Description                                | Example Value | Notes                                            |
+| ------------------ | ------ | -------- | ------------------------------------------ | ------------- | ------------------------------------------------ |
+| `actions`          | List   | Yes      | Defines the actions for the drop-down menu | N/A           | -                                                |
+| `actions.*.name`   | String | Yes      | Used as the action text                    | `Downloads`   | Example of a single action                       |
+| `actions.*.href`   | String | Yes      | Used as the action `href` atttibute        | `/resources/downloads` | Example of a single action              |
+
+**Active item**
+
+When the current page matches the `href` attribute of an action in a drop-down item, the drop-down action is made 
+active, and drop-down menu the active navbar item.
+
+**Example**
+
+```yml
+nav_items:
+  -
+    name: Resources
+    type: dropdown_item
+    actions:
+      -
+        name: Downloads
+        href: /resources/downloads
+```
+
+#### Related items
+
+Related items are comparatively  easier to define than internal items, it uses the same structure as the `single_item`
+internal item type.
+
+**Note:** Related items **SHOULD** always include entries for the BAS public website and BAS data catalogue.
+
+**Note:** Related items **SHOULD NOT** include non-BAS websites, as the drop-down menu title 'Part of the British 
+Antarctic Survey' implies its contents will be BAS operated websites.
+
+**Example**
+
+```yml
+nav_related_sites:
+  -
+    name: BAS Home
+    href: https://www.bas.ac.uk
+  - 
+    name: BAS Style Kit
+    href: https://style-kit.bas.ac.uk
+  - 
+    name: Discover BAS data
+    href: https://data.bas.ac.uk
+```
+
+### Cookie notice
+
+By law and by policy BAS websites are required to tell end-users whether cookies are used, and if so, where they can 
+find out more information about these cookies.
+
+It is assumed all BAS websites will use cookies, not least as all websites are expected to use analytics tracking,
+which depends on cookies.
+
+This theme provides a cookie banner to meet this need. It consists of:
+
+* the `phase` config option - which defines the URL to a page explaining how cookies are used on this website
+* the *Cookie banner* include - which displays a dismissible message and a link to the cookies usage page
+* the *Site footer* include - which includes a link to the cookies usage page
+* the *Body JS*  include - which includes the JavaScript needed to make the cookie banner dismissible
+
+The `cookies_href` config option **MUST** be set to a location with more information on how the website uses cookies.
+See the *Legal policies* section for more information.
+
+**Note:** This **SHOULD NOT** be the cookie policy used on the BAS public website, as it is not representative of our 
+other websites.
+
+### Development phase notice
+
+Websites exist at various stages of a development lifecycle - from inception, development, general availability through
+to retirement.
+
+Various points in this lifecycle are relevant to highlight to end-users, to give context and managing expectations.
+For example, new websites likely won't perform well, or have missing information.
+
+The BAS Style Kit, and this theme, support the 
+[development phases](https://www.gov.uk/service-manual/agile-delivery#phases-of-an-agile-project) defined by the 
+Government Digital Service (GDS) - these are:
+
+* Discovery - a stage before any website is built
+* Alpha - an early prototyping stage
+* Beta - a pre-release stage, things are expected to work correctly but with restrictions in terms of scale, 
+completeness or performance
+* Live - a service in general release - expected to work correctly without restrictions
+* Retirement - a service being wound down - expected to work until being shut-down, but no further improvements made
+
+This theme provides a development phase banner to inform end-users of the current development phase. It consists of:
+
+* the `phase` config option - which defines current development phase for the website
+* the *Phase banner* include - which displays information to end-users
+
+The `phase` config option **MUST** be set to one of these options:
+
+* `alpha`
+* `beta`
+* `live`
+* `retired`
+
+For all phases except live, a banner with a link to give site feedback will be shown. In the live phase no additional
+information is shown.
+
+**Note:** The *discovery* phase is not supported as website prototypes should only be made in the *alpha* stage.
+
+### Legal policies
+
+By law and by policy BAS websites are required to provide end-users with information on various legal policies. Namely:
+
+1. a copyright statement
+2. a privacy policy
+3. a cookies policy
+
+Links to these policies are displayed in the *Site footer* include, using config options to set their locations.
+
+#### Copyright statement
+
+The `copyright_href` config option **MUST** be set to a location with more information on how information on this 
+website is licensed, and how it can be used.
+
+It **MUST** document, which legal entity owns the content on the website, the license they make it available to 
+different auidences under, and what these users can and can't do as a result of this license.
+
+It **MUST** acknowledge other rights holders, and the terms under which they make their information available, if this
+applies. This may include information from other parts of BAS or NERC, which are licensed differently.
+
+The license under which the majority of the website's content is made available **SHOULD** be displayed in the site 
+footer, to make it easy to find by end-users. The phrase `Except where otherwise stated` can be used where multiple 
+licenses apply to different types of concept, providing this is suitably explained in the copyright statement, or next
+to the relevant content.
+
+Template policies which can be used as an example/base for such policies are being developed with relevant stake
+holders. Until these are ready contact the Web & Applications team for advice on what to put in such polices.
+
+**Note:** This **SHOULD NOT** be the copyright statement used on the BAS public website, as it is not representative of 
+our other websites.
+
+#### Privacy policy
+
+The `privacy_href` config option **MUST** be set to a location with more information on how user's information is used
+by the website.
+
+It **MUST** document if any personal information is collected from end-users, why it is collected, who will hold it 
+and process it, how long it will be held for, and how the end-user can access, update or remove this information.
+
+Template policies which can be used as an example/base for such policies are being developed with relevant stake
+holders. Until these are ready contact the Web & Applications team for advice on what to put in such polices.
+
+**Note:** This **SHOULD NOT** be the privacy policy used on the BAS public website, as it is not representative of our 
+other websites.
+
+#### Cookies policy
+
+The `cookies_href` config option **MUST** be set to a location with more information on how the website uses cookies.
+
+It should document the cookies used, what they are for and when they are set to expire. It should also provide 
+information on how users can view and manage cookies used by this website.
+
+Template policies which can be used as an example/base for such policies are being developed with relevant stake
+holders. Until these are ready contact the Web & Applications team for advice on what to put in such polices.
+
+**Note:** This **SHOULD NOT** be the cookie policy used on the BAS public website, as it is not representative of our 
+other websites.
+
+### Website feedback
+
+Feedback from end-users is vital to build a website based on their needs, rather than the needs we think they have.
+
+To this end, an easy to use mechanism for end-users to submit feedback **SHOULD** be available on all websites.
+
+This theme provides numerous links to a feedback URL, defined using the `feedback_href` config option. This **SHOULD**
+take the user to a form where they can provide feedback about the website.
+
+Links to this URL are shown:
+
+* in the site navigation, as the right most item
+* in the development phase banner, for development phases except *live*
+* in the site footer, as a 'is something wrong with this page?' link
+
+See the *Site navigation*, *Site footer* and *Development phase notice* sections for more information.
+
+## Development
+
+[Git](https://git-scm.com) and [Docker](https://www.docker.com/products/docker) [1] are required to build this project 
+locally.
+
+To update the Docker image for this project, access to the private 
+[BAS Docker Registry](https://docker-registry.data.bas.ac.uk) [2] is also required.
+
+```shell
+$ git clone https://gitlab.data.bas.ac.uk/BSK/bas-style-kit-jekyll-theme.git
+$ cd bas-style-kit-jekyll-theme
+
+$ docker-compose up
+```
+
+Go to [localhost:9000](http://localhost:9000) to preview 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] To install Git and Docker:
+
+**On macOS**
+
+```shell
+$ brew install git
+$ brew cask install docker
+```
+
+**On Windows**
+
+* Install Docker and Git using their respective installers
+
+[2] The first time you use this registry, you will need to authenticate using:
+`docker login docker-registry.data.bas.ac.uk`
+
+### Updating dependencies
+
+If `Gemfile` is changed, the project Docker image will need to be rebuilt and pushed to the private BAS Docker 
+Repository [1].
+
+The current project version is used as part of the project Docker image tag to ensure the latest version is used by all 
+developers. Before rebuilding this image you **MUST** update this tag value in `docker-compose.yml` and `.gitlab-ci.yml` 
+first.
+
+```shell
+$ cd jekyll-theme-bas-style-kit/
+
+$ 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`
+
+### Ruby Gem
+
+This theme is distributed as a Ruby Gem, through the public [Ruby Gems](https://rubygems.org) 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.
+
+## Release procedures
+
+1. bump version in `jekyll-theme-bas-style-kit.gemspec` and `docker-compose.yml`
+2. `docker-compose build`
+3. `docker-compose push`
+4. close release
+5. commit changes to git and tag with new version
+6. `docker-compose run app gem build jekyll-theme-bas-style-kit.gemspec`
+7. `docker-compose run app gem push jekyll-theme-bas-style-kit-*.gem`
+
+## Issue tracking
+
+This project uses issue tracking, see the 
+[issue tracker](https://gitlab.data.bas.ac.uk/BSK/bas-style-kit-jekyll-theme/issues) for more information.
+
+**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 at: webapps@bas.ac.uk.
+
+## License
+
+Copyright 2017 NERC BAS.
+
+Unless stated otherwise, all code is licensed under the MIT license.
+
+Copies of this licenses are included within this project.

data/_includes/layout/cookie-banner.html

@@ -0,0 +1,7 @@
+<div class="alert bsk-jekyll-alert-top-pin bsk-jekyll-alert-cookie-banner" id="site-cookie-banner" role="alert">
+  <div class="container">
+      <button type="button" class="close" data-dismiss="alert" aria-label="Close"><i class="fa fa-times-circle" aria-hidden="true"></i></button>
+      This website uses cookies to help us make it better -
+      <a class="alert-link" href="{{ site.cookies_href }}">find out more</a>.
+    </div>
+</div>

data/_includes/layout/phase-banner.html

@@ -0,0 +1,15 @@
+{% unless site.phase == 'live' %}
+<div class="container">
+  <div>
+    <span class="label bsk-jekyll-label-phase-{{ site.phase | downcase }}">{{ site.phase | upcase }}</span>
+    {% if site.phase == 'alpha' %}
+    This is a new website – your <a href="{{ site.feedback_href | prepend: site.baseurl }}">feedback</a> will help us to improve it.
+    {% elsif site.phase == 'beta' %}
+    This is a new website – your <a href="{{ site.feedback_href | prepend: site.baseurl }}">feedback</a> will help us to improve it.
+    {% elsif site.phase == 'retired' %}
+    This website is being shut down soon - <a href="{{ site.feedback_href | prepend: site.baseurl }}">contact us</a> if this will affect you.
+    {% endif %}
+  </div>
+  <hr />
+</div>
+{% endunless %}

data/_includes/layout/site-footer.html

@@ -0,0 +1,26 @@
+<footer class="footer-bsk footer-bsk-default site-footer">
+  <div class="container">
+    <!-- main content -->
+    <div class="pull-left">
+      {% include snippets/is-something-wrong.html %}
+    </div>
+    <div class="pull-right">
+        {% include snippets/back-to-top.html %}
+    </div>
+    <div class="clearfix"></div>
+    <div role="separator" class="footer-bsk-divider"></div>
+    <!-- Copyright & legal -->
+    <div class="footer-bsk-ogl">
+      <a class="ogl-symbol" rel="license" href="http://www.nationalarchives.gov.uk/doc/open-government-licence/"><img alt="Open Government Licence logo" src="https://s3-eu-west-1.amazonaws.com/bas-cdn-dev/scratch/bas-style-kit-jekyll-theme/img/ogl-symbol-white.png"></a>
+      <div class="ogl-text">All content is licensed under the <a href="http://www.nationalarchives.gov.uk/doc/open-government-licence/">Open Government Licence v3.0</a>, except where otherwise stated</div>
+    </div>
+    <div class="footer-bsk-policy-links">
+      © {{site.time | date: "%Y"}} NERC BAS
+      <ul class="list-inline">
+        <li><a href="{{ site.copyright_href }}">Copyright</a></li>
+        <li><a href="{{ site.privacy_href }}">Privacy</a></li>
+        <li><a href="{{ site.cookies_href }}">Cookies</a></li>
+      </ul>
+    </div>
+  </div>
+</footer>

data/_includes/layout/site-navigation.html

@@ -0,0 +1,68 @@
+<nav class="navbar navbar-bsk navbar-static-top site-navigation">
+    <div class="container">
+      <!-- Site name and toggle get grouped for better mobile display -->
+      <div class="navbar-header">
+        <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#site-navbar-collapse" aria-expanded="false">
+          <span class="sr-only">Toggle navigation</span>
+          <span class="icon-bar"></span>
+          <span class="icon-bar"></span>
+          <span class="icon-bar"></span>
+        </button>
+        <a class="navbar-brand" href="/">{{ site.title }}</a>
+      </div><!-- /.navbar-header -->
+
+      <!-- Collect navigation items, links, forms etc., for toggling -->
+      <div class="collapse navbar-collapse" id="site-navbar-collapse">
+        <ul class="nav navbar-nav">
+        {% for item in site.nav_items %}
+            {% comment %} Single navbar items {% endcomment %}
+            {% if item.type == 'single_item' %}
+            {% assign page_url = page.url | remove: '.html' %}
+            <li {% if page_url == item.href %} class="active"{% endif %}>
+                {% if page_url == item.url %}<span class="sr-only">(current)</span>{% endif %}
+                <a href="{{ item.href }}">{{ item.name }}</a>
+            </li>
+
+            {% comment %} Dropdown navbar items {% endcomment %}
+            {% elsif item.type == 'dropdown_item' %}
+                {% assign page_url = page.url | remove: '.html' %}
+                {% for action in item.actions %}
+                    {% if page_url == action.href %}
+                        {% assign is_active = true %}
+                    {% endif %}
+                {% endfor %}
+            <li class="dropdown {% if is_active %}active{% endif %}">
+                <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">
+                {% if is_active %}<span class="sr-only">(current)</span>{% endif %}
+                {{ item.name }} <span class="caret"></span></a>
+                <ul class="dropdown-menu dropdown-menu-bsk">
+                {% for action in item.actions %}
+                    <li {% if page_url == action.href %} class="active"{% endif %}>
+                        {% if page_url == action.href %}<span class="sr-only">(current)</span>{% endif %}
+                        <a href="{{ action.href }}">{{ action.name }}</a>
+                    </li>
+                {% endfor %}
+                </ul>
+            </li>
+            {% endif %}
+        {% endfor %}
+        </ul><!-- /.navbar-nav -->
+
+        <ul class="nav navbar-nav navbar-right">
+          <li class="dropdown">
+            <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">
+              Part of the British Antarctic Survey <span class="caret"></span>
+            </a>
+            <ul class="dropdown-menu dropdown-menu-bsk">
+              {% for item in site.nav_related_sites %}
+              <li><a href="{{ item.href }}">{{ item.name }}</a></li>
+              {% endfor %}
+            </ul>
+          </li>
+          <li>
+            <a href="{{ site.feedback_href }}">Feedback</a>
+          </li>
+        </ul><!-- /.navbar-nav .navbar-right -->
+      </div><!-- /.navbar-collapse -->
+    </div><!-- /.container -->
+</nav>

data/_includes/snippets/back-to-top.html

@@ -0,0 +1 @@
+<a class="back-to-top" href="#site-top"><i class="fa fa-arrow-up" aria-hidden="true"></i> Back to top</a>

data/_includes/snippets/body-js.html

@@ -0,0 +1,8 @@
+<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
+<script src="https://cdn.web.bas.ac.uk/js-libs/jquery-3.1.1.min.js"></script>
+<!-- Compiled and minified Bootstrap JavaScript plugins, include individual plugins instead if needed -->
+<script src="https://cdn.web.bas.ac.uk/js-libs/boostrap-3.3.7.min.js"></script>
+<!-- Cookie library used to persistently hide the cookie banner (slightly ironic we need a cookie to do this) -->
+<script src="https://cdn.web.bas.ac.uk/js-libs/js.cookie-2.1.3.min.js"></script>
+<!-- Code for managing cookie banner -->
+<script src="{{ '/assets/bsk-jekyll/js/cookie-banner.js' | prepend: site.baseurl }}"></script>

data/_includes/snippets/google-analytics.html

@@ -0,0 +1,12 @@
+<script>
+  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
+
+  ga('create', '{{ site.ga_property }}', 'auto', {
+    anonymizeIp: true
+  });
+  ga('send', 'pageview');
+
+</script>

data/_includes/snippets/head.html

@@ -0,0 +1,29 @@
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <!-- The above 3 meta tags *must* come first in the head -->
+    <title>{% if page.title %}{{ page.title | escape }} &middot; {{ site.title | escape }}{% else %}{{ site.title | escape }}{% endif %}</title>
+    <meta name="description" content="{% if page.excerpt %}{{ page.excerpt | strip_html | strip_newlines | truncate: 160 }}{% else %}{{ site.description }}{% endif %}">
+    <link rel="canonical" href="{{ page.url | replace:'index.html','' | prepend: site.baseurl | prepend: site.url }}">
+
+    <!-- Favicons -->
+    <link rel="apple-touch-icon" sizes="152x152" href="{{ "/bsk-jekyll/img/apple-touch-icon.png" | prepend: site.baseurl }}">
+    <link rel="apple-touch-icon-precomposed" sizes="152x152" href="{{ "/bsk-jekyll/img/apple-touch-icon.png" | prepend: site.baseurl }}">
+
+    <!-- Compiled and minified customised Bootstrap CSS for the BAS Style Kit -->
+    <link rel="stylesheet" href="https://cdn.web.bas.ac.uk/bas-style-kit/0.1.0/css/bootstrap-bsk.min.css" integrity="sha256-LcHhV+YQv+6Le1nrMcfpE3YoFYIvnfC8mtEa6IC4r48=" crossorigin="anonymous">
+    <!-- Compiled and minified BAS Style Kit CSS -->
+    <link rel="stylesheet" href="https://cdn.web.bas.ac.uk/bas-style-kit/0.1.0/css/bas-style-kit.min.css" integrity="sha256-BtBOHsRYohQJ5q9Lpjs53snUSKyMuV2bYkPEAmQH56o=" crossorigin="anonymous">
+    <!-- Theme specific styles -->
+    <link rel="stylesheet" href="{{ "/assets/bsk-jekyll/css/jekyll-theme-bas-style-kit.css" | prepend: site.baseurl }}">
+    <!-- Site specific styles -->
+    <link rel="stylesheet" href="{{ "/assets/css/main.css" | prepend: site.baseurl }}">
+    
+    <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
+    <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
+    <!--[if lt IE 9]>
+      <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
+      <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
+    <![endif]-->
+</head>

data/_includes/snippets/is-something-wrong.html

@@ -0,0 +1 @@
+<a href="{{ site.feedback_href | prepend: site.baseurl }}">Is something wrong with this page?</a>

data/_layouts/blank.html

@@ -0,0 +1 @@
+{{ content }}

data/_layouts/default.html

@@ -0,0 +1,20 @@
+---
+layout: html
+---
+
+<div id="site-top"></div>
+<a href="#site-content" class="sr-only sr-only-focusable">Skip to main content</a>
+{% include layout/cookie-banner.html %}
+{% include layout/site-navigation.html %}
+{% include layout/phase-banner.html %}
+
+<main class="container site-main">
+    {{ content }}
+</main>
+
+{% include layout/site-footer.html %}
+
+{% include snippets/body-js.html %}
+{% if ga_property %}
+{% include snippets/google-analytics.html %}
+{% endif %}

data/_layouts/html.html

@@ -0,0 +1,12 @@
+---
+layout: blank
+---
+
+<!DOCTYPE html>
+<html lang="en-GB">
+    {% include snippets/head.html %}
+
+    <body>
+        {{ content }}
+    </body>
+</html>

data/assets/bsk-jekyll/css/jekyll-theme-bas-style-kit.scss

@@ -0,0 +1,75 @@
+---
+---
+@charset "utf-8";
+
+//
+// Additioanl styles specific to Jekyll websites using the BAS Style Kit
+//
+
+// Styles for extending the colour of the footer to fill pages where there isn't enough content to fill the viewport
+// These will be merged into a future version of the BAS Style Kit
+
+html {
+  background-color: #333;
+}
+.site-main {
+  min-height: 300px;
+}
+
+// Styles for Cookie banner 
+// These will be merged into a future version of the BAS Style Kit
+//
+
+.bsk-jekyll-alert-top-pin {
+  margin-bottom: 0;
+
+  border: none;
+  border-radius: 0;
+}
+
+.bsk-jekyll-alert-cookie-banner {
+  background-color: #006AAA;
+  color: white;
+
+  .alert-link {
+    color: white;
+  }
+
+  .close {
+    filter: alpha(opacity=70);
+    opacity: .7;
+    color: #E7EBF1;
+
+    &:focus, &:hover {
+      filter: alpha(opacity=100);
+      opacity: 1;
+    }
+  }
+}
+
+// Sryles for development phase banner
+// These will be merged into a future version of the BAS Style :-webkit-any()
+//
+
+.bsk-jekyll-label-phase-alpha,
+.bsk-jekyll-label-phase-beta,
+.bsk-jekyll-label-phase-live,
+.bsk-jekyll-label-phase-retired {
+  border-radius: 0;
+  font-weight: normal;
+}
+
+.bsk-jekyll-label-phase-alpha {
+  background-color: #D53880;
+  color: #333;
+}
+.bsk-jekyll-label-phase-beta {
+  background-color: #F47738;
+  color: #333;
+}
+.bsk-jekyll-label-phase-live {
+  background-color: #85994B;
+}
+.bsk-jekyll-label-phase-retired {
+  background-color: #6F777B;
+}

data/assets/bsk-jekyll/js/cookie-banner.js

@@ -0,0 +1,32 @@
+jQuery(function($){
+
+  // Look for cookie to hide cookie banner
+
+  var cookieBannerValue = Cookies.get('seen_cookie_message');
+
+  if (typeof cookieBannerValue !== 'undefined') {
+    if (cookieBannerValue == 'yes') {
+
+      // Supress cookie message
+      // Since we already have jQuery available we may as well use its convenience methods
+      jQuery('#site-cookie-banner').remove();
+    }
+  }
+
+  // React to closing the cookie banner
+
+  jQuery('#site-cookie-banner').on('close.bs.alert', function () {
+
+    // Set a cookie to persist hiding the cookie banner for the next 30 days
+    var cookie_name = '';
+    var cookie_value = 'yes'
+
+    Cookies.set(
+      'seen_cookie_message',  // cookie name
+      'yes',                  // cookie value
+      {
+        expires: 30           // in days
+      }
+    );
+  })
+});

data/assets/css/main.scss

@@ -0,0 +1,7 @@
+---
+---
+@charset "utf-8";
+
+//
+// Additioanl styles specific to this website
+//

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-bas-style-kit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Felix Fennell
@@ -58,7 +58,29 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE-MIT.md
+- LICENSE.md
+- README.md
+- _includes/layout/cookie-banner.html
+- _includes/layout/phase-banner.html
+- _includes/layout/site-footer.html
+- _includes/layout/site-navigation.html
+- _includes/snippets/back-to-top.html
+- _includes/snippets/body-js.html
+- _includes/snippets/google-analytics.html
+- _includes/snippets/head.html
+- _includes/snippets/is-something-wrong.html
+- _layouts/blank.html
+- _layouts/default.html
+- _layouts/html.html
+- assets/bsk-jekyll/css/jekyll-theme-bas-style-kit.scss
+- assets/bsk-jekyll/img/apple-touch-icon.png
+- assets/bsk-jekyll/js/cookie-banner.js
+- assets/css/main.scss
+- screenshot.png
 homepage: https://gitlab.data.bas.ac.uk/BSK/bas-style-kit-jekyll-theme
 licenses:
 - MIT