Use npm to install the necessary gulp-cli:
npm -g install gulp-cli
Install all required packages:
npm install
Build the style guide:
gulp build
Run the local webserver using gulp:
gulp
Browse to localhost:9000.
To run accessibility test (local webserver has to be running):
gulp test
Results are available in pa11y/index.html
(open in your browser, e.g. firefox pa11y/index.html
) and pa11y/report.json
(open with jq
).
Configuration is in .pa11y
.
The styleguide is generated from source sass files with kss.
In order to add new section to the styleguide you need to add a specific format of comment block to the appropriate partial file.
For instance adding this on top of _buttsons.scss:
// Buttons
//
// Markup:
// <div class="mb-2">
// <a href="/international/act/protect-the-oceans/" class="btn {{modifier_class}}">Protect our seas</a>
// </div>
//
// .btn-primary - Primary button
// .btn-secondary - Secondary button
//
// Styleguide Components.buttons
Let's break this down:
- Pick the title for that section.
// Buttons
- Add the markup that you want to use as an example. It's important to add the word
Markup:
there.
// Markup:
// <div class="mb-2">
// <a href="/international/act/protect-the-oceans/" class="btn {{modifier_class}}">Protect our seas</a>
// </div>
- Optionally, you can have some variations. The classes defined here will substitute the
{{modifier_class}}
variable on the markup above.
// .btn-primary - Primary button
// .btn-secondary - Secondary button
- Last thing on the comments block should be the hierarchy of the section, so that kss knows where to place it.
// Styleguide Components.buttons
Our theme is based on the michelangelo kss theme, with some modification to meet the same look and feel we have on planet 4.
We can do changes on the theme by modifiying its sass code in the theme/kss-assets/css folder.
Every time we run gulp build
, we generate both the styleguide theme, but also the unified css from our source files. The output folder is dist
.
Running gulp
we initiate the watch task and run a webserver at localhost:9000.
The build and deployment is happening automatically whenever:
- There are commits to the master branch.
- There are new tags created.
The above changes trigger (via the circleCI API) a rebuild of the develop and master related workflows of the current repository.
These in turn do the following:
- Checkout the relevant code of the styleguide (either the latest code of the master theme, or the latest tag).
- Create a docker image with the above code in the repository called "public".
- Push this docker image to the docker hub registry for the current application and tag it either
develop
orlatest
. - Run a helm deploy/update to create the necessary kubernetes resources so that this can be served by our kubernetes clusters.
- This repository does not have its own helm chart. It utilises the helm chart Planet4 static which can been created to accomodate all static applications.
- New commits to the master branch get deployed at the url: https://develop.planet4.greenpeace.org/styleguide/
- New tags get deployed at the url: https://planet4.greenpeace.org/styleguide/
- At the bottom left corner of those implementations you can see the hash (or the tag number) of the code used to build it.