Home

Developing the WIP web pages

This page describes one way, possibly not the optimal one, for getting set up to develop changes to the WIP web pages. The Github pages system we are working with is built upon Jekyll, a Ruby based system for creating static Markdown based websites.

Any reasonably recent version of Jekyll requires an up to date version of Ruby to operate and many institutional IT facilities may not provide this (true of Met Office and JASMIN (CEDA) at least). Instead, it is possible to create a conda environment in which to host the Ruby & Jekyll installation. If you do not have a conda installation, the simplest way to set one up is to download and install miniconda and then follow the procedure below

1. Checkout this repository and create your own branch to develop on

2. Create a new environment based on the environment.yml YAML file:

   conda env create -n wip_jekyll environment.yml

   This should download and install the dependencies required to run Ruby and jekyll and create a new conda environment named wip_jekyll that you can activate when working on this repository

3. Install Jekyll using the Ruby gem command:

   gem install bundler jekyll

4. Install the jekyll themes needed to work with Github pages

   gem install github-pages

5. If all has gone well you should then be able to launch the jekyll web server by navigating to the docs directory of the repository and running

   bundle exec jekyll server

This will launch a local webserver (on port 4000 by default) and content will be regenerated as files are modified/added

Should you see errors talking about missing gems, try deleting the docs/Gemfile.lock file and retrying.

Notes on understanding web page set up

Structure

The web pages are "served" from the /doc folder within the repository; all files used for these pages (including all the jekyll stuff) must be under this folder.

Theme

I believe Jekyll allows switching between themes. I've picked up the bare minimum of additions from the pages-themes/minimal theme, but there are many other options if required.

Front matter

Front matter on a markdown page is between ---, e.g.

---
title: Page title
rank: 9
---
# Page title (can be different)

Content

The rank is used for the sort order in the side bar. All pages with this front matter will appear in the side bar.

_layout/default.html

This was constructed from the minimal template on a trial and error basis. In theory this should not need to be edited, unless you are changing the structure of the side bar.

Note that changes made in #22 mean that only pages at the top level are included in the contents list

assets/css/style.scss

This is a tweak to modify the default link behaviour (avoid mouse over changing links to bold and paragraphs jumping around)

_config.yml

This has a few top level settings that are picked up in the side bar via the layout default.html page. If these are modified you'll need to restart the jekyll server process.

Links

To link to a markdown page from within another I think the following works:

`[Link text]({% link location/filename.md %})`

The {% link ... %} text is a Liquid tag link that returns the location of the corresponding html file.