About the theme#

jekyll-theme-anu is a Jekyll theme that can be used by static sites (no backend) written in Jekyll. It provides ANU brand compliant assets, layouts, includes, and stylesheets in a way that can be overridden by each site’s content.

The theme has been developed with the following priorities in mind:

  1. compliant with the (new) ANU Identity Guidelines
  2. accessibility (strives to meet WCAG 2.1 at Level AA)
  3. modern browsers (modern = CSS grid)
  4. responsive (mobile-first)
  5. minimal js (things should work as much as possible even without js)
  6. no unnecessary coupling to Jekyll (because it might be used as the base for some twig (drupal) templates, or we might move to a new SSG in the future)

You don’t need to modify the theme (or to even know how to do that) to create a new ANU-themed Jekyll website. You don’t even need to modify the theme to tweak the look & feel of your website. The main reason to contribute to the theme directly is if you’re developing something that will be useful for all users of the theme—if that’s the case, then that’s great, and you should drop into the main Jekyll support Team to discuss your idea and how we can best bring it into the main theme.

Local development setup#

To contribute to the ongoing development of the Jekyll theme, you’ll need to set up your local development environment with the theme, as well as a website that uses the theme in order to test your changes.

1. Install Jekyll#

Follow the relevant guide in order to install Jekyll on your system.

2. Clone repos#

First you’ll need the correct Gitlab access and to set up your Gitlab SSH key.

Then, clone the following repos:

# Theme repo
git clone git@gitlab.anu.edu.au:jekyll-anu/gems/jekyll-theme-anu.git

# At least one site that uses the theme for testing. If you're making
# changes for a specific site, you can clone the repo for that site.
# Otherwise, the line below clones jekyll-anu-website-template-repo,
# which is a template for new sites uses many of the theme features.
git clone git@gitlab.anu.edu.au:jekyll-anu/docs/jekyll-anu-website-template-repo.git

# (optional) Plugins repo - only clone if you're developing plugins
git clone git@gitlab.anu.edu.au:jekyll-anu/gems/jekyll-plugins-anu.git

We can’t build or serve the theme or plugins gems directly, so we have to test changes to them by locally running a site that uses the theme and plugins gems.

It’s a good idea to test your changes across different sites as they might have different configurations which interact with the theme in different ways.

3. Bundler config#

Jekyll uses bundler to manage dependencies. You’ll want to set up the local development environment for the site you’re testing with so that bundler uses your local copies of the theme and plugins gems instead of the latest released copies.

You can do this by running in the site repo:

# Change into the site repo, e.g.
cd jekyll-anu-website-template-repo/

# Configure bundler to use local theme gem
bundler config local.jekyll-theme-anu path/to/jekyll-theme-anu

# (optional) Only run if you're developing plugins
# Configure bundle to use local plugins gem
bundler config local.jekyll-plugins-anu path/to/jekyll-plugins-anu

# Install gems
bundle install

4. Serve site locally#

Build and serve the site locally:

bundle exec jekyll serve

Site taking a long time to build? If the site is taking a long time to build, this might be due to the autoprefixer plugin which can take up to a few minutes. To disable it for local development, uncomment out the only_production: true setting in config.yml:

autoprefixer:
  browsers:
    - last 2 versions
  # uncomment out line below to turn off autoprefixing and speed up local build for development
  only_production: true

Remember not to commit this change.

5. Reload server#

Normally, if you’re making changes to the site, you can use the builtin live reload functionality. However, if you’re modifying the theme or plugin gems, the --livereload flag doesn’t work.

This means you’ll need to manually stop and start the server for the site each time you make changes.

Alternatively, you can follow to steps below to install jekyll-dev - a node module for theme-based live reload. It’s a bit involved so this is only recommended if you’re doing a lot of development work on the theme.

  1. Install node v11.15.0 (recommend you use a node version manager like nvm)
  2. Make sure you’re using node v11.15.0 in the site folder (my workflow is to place a .nvmrc in the root containing v11.15.0 and run nvm use)
  3. Install jekyll-dev 
      npm install -g jekyll-dev
  4. Serve site locally by running jekyll-dev

    If the site has a baseurl set in config.yml then the HTML proofer will fail when using jekyll-dev. If this happens, you can locally disable HTML proofer by commenting it out in config.yml:

       # jekyll_proofer: warn

    Remember not to commit this change.

  5. Profit (or at least no more manual server reloading)

6. Git workflow#

This process may be in flux. If you’re not sure what to do, contact CECS Jekyll web support.

In general, you’ll want to work in a develop branch or your own feature branch, and avoid pushing up changes directly to the master branch of the theme, as there are live websites using the theme.

cd jekyll-theme-anu/
git checkout develop
#
# You make, test, and commit some local changes
#
git pull origin master    # pull down any changes to the theme
git rebase origin/master  # rebase your branch on top of master
git push
arrow-left bars search times