Eventually this guide will become part of the Handbook on the website.
Please flag any issues with these instructions as I have mostly written from memory!
git clone
or GitHub Desktop.
gh-pages
.bundle install
arch -arch x86_64 bundle install
if the above does not work.bundle exec jekyll serve --livereload
arch -arch x86_64 bundle exec jekyll serve
if the above does not work.--livereload
option enables you to see changes to your code automatically in your browser, without rebuilding the code.--livereload
option does not work with changes to the config.yml
file. In this case, you will need to re-run bundle exec jekyll serve --livereload
.The CSC site is built on Jekyll and incorporates Bootstrap v5 for CSS and java. Useful links relating to these are in the Resources section below.
For a thorough explanation of this, consult the Jekyll website. This is an abridged alternative. The directory structure of the website is approximately as follows:
.
├── _data
├── _layouts
├── _includes
├── _sass
├── _site
├── assets
│ ├── css
│ ├── img
│ └── js
│
├ ._config.yml
├ Gemfile
└ multiple .md files
_data
– this folder contains .yml files which contain the actual 'data' within the website. i.e.: the content that goes into the calendar, info about team members, etc. Once we have designed the layouts of the pages, we should be able to just update the files in here with new content. In theory...
_layouts
– this folder contains html files which determine different page layouts. The layouts can be called in the YAML frontmatter of a page, e.g.: layout: platforms
applies the _layouts/platforms.html
_includes
– this folder contains html snippets which can be 'included' in other pages, hence it's called "_includes". For instance, the code for the CSC calendar is in here which is used in two places: 1) the home page and 2) the actual dedicated Calendar page. This enables modular design and avoids code duplication.
_sass
– this contains the CSS for the site, which determines colours, padding, background colours, etc. SASS is basically fancy, enhanced CSS. Note: styling is also controlled in some other files, such as the _config.yml
, assets/css/
and a few other places.
_site
– Do NOT edit these files. Jekyll creates the website from the .md, .html, .css, etc. files and puts the compiled website in this folder.
assets
– contains CSS, Javascript and image files. Can have subdirectories, such as img/team
which contains all the photos of the CSC team.
._config.yml
– The configuration file for the website. Determines various important things which propagate across the entire site. Can have lots of content.
.md files
– Markdown files which form the basic building blocks of the website. In Jekyll, if you use the Liquid filter {{ content }}
then the contents of the .md file are input. You can also call files from the _includes
folder using the Liquid tag {% include file-in-_includes.html %}
.
Let's pretend to create the Team page on the website.
team.md
team.md
:
---
layout: aboutus
title: Meet the Team
---
layout: aboutus
calls the _layout/aboutus.html
file, which in turn uses Liquid: {% include subnav-aboutus.html %}
, hence we get the correct subnav bar.title: Meet the Team
is assigned a <h1>
heading tag in the aboutus.html
._includes
which contains the the structure of the Team page. I've already made one called team.html
._data/team.yml
.
_includes/team.html
has already been configured to loop through however many team members exist in the .yml
file!_data/team.yml
, in your .html file, you need to use a Liquid tag, a bit like this: {% for name in site.data.team[site.locale].team.people.name %}
, which will loop over all the team member names.If you're happy with your changes, push your feature branch to the repo on GitHub, submit a pull request and ask someone to review your changes.
The nuts and bolts of the website.
Determines the styling of the website, such as CSS and Java.
Important: Bootstrap is designed to be responsive, which means that the website is optimised for both large computer screens and small mobile phone screens.
F12
).