Getting started

Github

If you are reading this, I guess you have already cloned Greenwire GitHub repository into your developing branch. Don't know what is Github? Check GitHub documentation. Set it up and learn some basics if you haven't yet.

Once you setup GitHub, you can clone Greenwire repository in your developing branch using the terminal:

$ git clone git@github.com:greenpeace/ggw_styleguide.git

Middleman

We are using Middleman to generate this styleguide. Middleman is a command-line tool for creating static websites using all the shortcuts and tools of the modern web development environment.

Running the styleguide locally

To simplify the development workflow a Docker config is available. First you will need to install docker. Then open the docker quickstart terminal and go to your project directory and type:

$ docker-compose up -d

This command will build a container based on docker-compose.yml and Dockerfile located at the root of the project directory. It may take a while to build as docker will download and build all the dependencies. Once this is done, you should be able then see the site at http://192.168.99.100:4568 You can get a terminal to execute commands inside the container with the following:

$ docker exec -it middleman bash

To check if the docker container is running you can try the following command:

$ docker ps
CONTAINER ID        IMAGE                     COMMAND                  CREATED             STATUS              PORTS                    NAMES
19c82396f1f8        ggwstyleguide_middleman   "/bin/sh -c 'middlema"   16 minutes ago      Up 16 minutes       0.0.0.0:4568->4567/tcp   middleman

An alternative way to start the docker container without middleman starting by default is to use the command:

$ docker-compose run --service-ports middleman bash

You can stop the preview server from the command-line using CTRL-C.

Publishing the static site (middleman deploy)

Finally, when you are ready to deliver static code, you will need to build and deploy the site. From within the root of the container execute sh middleman_deploy.sh. This will first create a new build and then checkout to the gh-pages branch and push the changes there. You can also do a %code sh middleman_build.sh to check your changes before deploying.

$ sh middleman_deploy.sh

Changing CSS

All CSS that is used is generated with GulpJS. This is also what you need to have installed locally (not part of Docker container).

In the project folder you will find a package.json file. In this file you find all the gulp plugins you need.

First make sure you have gulp installed on your machine:

$ npm install --global gulp

To install the gulp plugins and gulp itself in the project you can simple run the following commands from the theme (this) folder.

$ npm install

To start compiling you scss files into css, you can use the following gulp task:

$ gulp

What this task does can be found in the gulpfile (default). It will automically open the styleguide in your browser, including livereload. You do not have to use this feature each time you work on the theme, it is just default behavior of the gulp tasks.