creation of a local version such that PR's are qualified

[OwenBrotherwood]

how to create a local version of the docs that looks like tech.microbit.org when run such that PR's have the best quality possible

[whaleygeek]

We install Jekyll and serve locally. Let me find the instructions, hang on a tick.

[whaleygeek]

This will make it into the readme eventually, but try this:

Structure

Here is good background reading on structuring multi-lingual sites in Jekyll without special plugins: https://www.sylvaindurand.org/making-jekyll-multilingual/. This site makes some improvements to that example to make language more manageable.

In particular, language tags (short strings re-used across pages) are each stored in their own gettext PO file under /_data. For example for Finnish the following file contains definitions of tags. These PO files are converted to YML (currently manually using a tool, see below).

/_data/fi.po

Each language has a directory, such as /fi and /fr, in which a localised version of each page is included. The page MUST have a lang: [language] front matter setting.

Each post is also marked in its own language using a lang: front matter setting.

Requirements

Jekyll 3.2.1 Ruby v2 of above RubyGems NodeJS i18n-translator-tools gem

Installation - quick and easy

Assuming you already have Ruby and RubyGems installed (most Linux and Mac machines), installing Jekyll is easy if you want to use the pre-installed system wide Ruby. This sort of presumes that it's reasonably up to date.

sudo gem install jekyll

sudo gem install bundler

Then in the root of this project setup any plugins used by typing

sudo bundle

Installation - slower but more flexible

Assuming you want a custom install, i.e. a standalone Ruby, without mucking about with your system install

For example, on OS X:

brew install rbenv ruby-build gem install bundler eval $(rbenv init -) rbenv install 2.3.1 rbenv global 2.3.1

check your ruby version with

ruby -v

and now proceed with installation:

gem install jekyll bundle

Building and testing

To build the site simply type

jekyll build

Or try

bundler exec jekyll build

This will place the static site under _site. Then to host on http://localhost:4000 for testing type

jekyll serve

Or try

bundler exec jekyll serve

Local Development

There is a config file which will allow local testing to work more easily, for example seting the site location to 127.0.0.1.

You can use this typing `bundle exec jekyll serve --config _config.yml,debug.yml

Language updates

To update the translatiosn from .po to .yml use the following script, which depends on the i18n-translator-tools gem. This is only needed when translations are updated.

./i18n

[OwenBrotherwood]

Then in the root of this project setup any plugins used by typing sudo bundle

bundle wants a gem file and there doesn't seem to be any

[jaustin]

I pull the docs from this branch into a wider structure. We should pull more of that out here to allow better rendering.

More to the point, we should actually have a way to preivew changes on our own staging site, etc, etc.

[OwenBrotherwood]

I know the feeling :)