Getting started (for site developers)

One audience for this documentation is “site developers”. This might be you if you’re:

• using Jekyll for your course website¹
• maintaining/adding significant new functionality to one of the School websites
• creating a new page for your “research group/lab/studio”

If you’re just looking to create/modify content (rather than the actual structure of the sites) then you might be better off starting with the getting started for content creators page—because you don’t have to do any of the stuff below to modify content on an existing site.

This page is broken into two parts—the initial setup and the (ongoing) workflow for developing your course website.

Initial setup#

You only have to do this stuff once. You can also do some of these steps in parallel, e.g. you can get your Ruby setup working while you’re waiting to hear back from the Computing Facilities Team.

Ruby setup#

Jekyll is a static site generator: you give it some content (in the form of text files) and it spits out a website. This is done by a jekyll command-line tool which runs on your machine. The tool is written in Ruby, you’ll need a working Ruby software development environment:

We recommend using rbenv to manage your Ruby installation, but you can install Ruby directly or through your favourite package manager as below:

1. Ruby (v3.2)—the linked page has installation instructions for several different platforms; Version 3.2.x is necessary. <= 3.1 and >= 3.3 both cause errors for the ANU Jekyll theme (last checked Jan 2025).

2. a copy of RubyGems. If you’ve installed Ruby through a package manager this might already be installed (check by seeing what happens when you run the gem command)

3. bundler, to make sure your site always runs with the correct versions of dependencies. You can install this using RubyGems: gem install bundler

Note to macOS users: macOS does ship with a very old version of ruby, and trying to use it will probably be painful. The recommendation is to install ruby some other way (e.g. Homebrew is a good option if you don’t have strong sysadmin-y preferences, but other ways are fine as well).

bundle exec jekyll build

If you need a way of running multiple versions of Ruby for different projects, then rbenv is a useful tool. However, if Jekyll is the only Ruby project you’ll be working on, it’s probably ok to just install the appropriate Ruby version and gem install bundler as described above.

SOCO Facilities setup#

Before you (or anyone else) will be able to see your Jekyll website on the internet, you need to contact the SOCO Facilities Team.

1. send an email to the facilities team with the subject New Jekyll Course website for COMPXXXX so they can create a fork of the Jekyll ANU template for you at https://gitlab.cecs.anu.edu.au/courses/compXXXX

Wherever you see “COMPXXXX” mentioned in this guide, replace the “XXXX” with your course code, e.g. COMP1720. There’s not even any requirement that the website name matches the COMP[0-9]{4} regex, so if your course spans several course codes (e.g. our honours/project courses, or some “special topics” courses) then we can pick a URL stub which makes sense for your course.

Jekyll setup#

Once the Computing Facilites Team team have created it for you, you should clone the newly-created GitLab project (which represents the source material for your course website) to your local machine. Navigate to the folder where you want to store your site and run:

# replace XXXX with your course code
git clone https://gitlab.cecs.anu.edu.au/courses/compXXXX.git

Once you’ve got the template website repository on your computer, and assuming you’ve completed the ruby setup described above, navigate to the folder (ie. cd compXXXX) and use bundler to install the dependencies: bundle install. This may take a few minutes to complete depending on how fast your computer is.

Configuring the template website#

To complete the initial setup you need to update the site’s configuration so that it reflects the fact that this website isn’t the default template website anymore—it’s your website.

YAML crash course#

A Jekyll site’s main configuration is stored in _config.yml, which is a YAML file. Jekyll uses YAML files extensively for configuration, so here’s a little “YAML crash course”:

1. foo: bar describes a variable “foo”, with the value “bar”

2. you can have keys inside of keys, to create an object

   person: 
     name: Ada Lovelace
     birthday: 10th December 1815
   

3. you can also have a list inside a key to create an array (and the elements of an arrays can be objects, or a plain value)

   people:
   - name: Lucy Suchman
     position: Professor
     DOB: null
   - name: Alan Turing
     position: Fellow
     DOB: 1912-06-23
   - name: Peter Shor
     position: Jr. Professor
     DOB: 1959-08-14
   

This is just the crash course—if you’d like to know more about how to use this structured data in your web pages, see the Programming pages guide.

Modifying _config.yml#

To configure your template website, open the _config.yml file in your favourite text editor. The file is mostly self-documenting, and will clue you into the different options you have when setting up your site.

Starting off, you’ll want to change:

1. the value of the baseurl field. Set this to the “subdirectory” of your web site, eg. "/courses/comp1234" if your sites full URL is https://comp.anu.edu.au/courses/comp1234. If your site sits at the “top” of it’s domain, then leave it blank: "", as would be the case for (eg.) https://eng.anu.edu.au.

2. title (the full name of your course) and short_title (the course code, including the COMP prefix)

3. contacts by adjusting the name and email keys under responsible_officer and page_contact.

Note that compared to the previous theme, the navbar menu (menu in _config.yml) and collections (collections in _config.yml) are now separate.

Nice job—you’ve configured the website template to be your own. Now you can start modifying the actual content on your site.

Developing your course website#

Local development setup#

First you’ll need to setup an SSH key on Research GitLab. If your website repository is located on Teaching GitLab then you’ll need to add the same SSH key here. This will allow you to authenticate against the jekyll-theme repositories.

Finally, clone your website repository using SSH. If you use https you will be prompted for the password for git@gitlab.anu.edu.au in the next step.

Starting the preview server#

When you’re writing content (e.g. assignments, labs, lecture slides, admin pages) for your course website, it’s handy to see how it will look when it’s published online. If this is the first time you’re doing this, or if you’ve made an update to the Gemfile, you’ll need to run bundle’s install command:

bundle install

This command installs the ruby gems necessary to build the website. Then, you can run Jekyll’s serve command:

bundle exec jekyll serve

This command starts a webserver on your local machine to show a “preview” of your website. To see it, point your web browser at the server address—which Jekyll will have printed to the terminal like so:

Server address: http://127.0.0.1:4000/courses/COMPXXXX/

bundle exec jekyll serve --help

The exception to the serve command’s “change the file, see the results in the browser” workflow is that any changes made to _config.yml won’t show up when you just refresh the page. To see them you’ll to stop and restart the bundle exec jekyll serve command, e.g. with the ctrl-c.

Navigating the site and writing some content#

Open up index.md with your favourite editor. This is the content that will end up on the main landing page—the first thing students will see when they come look at your site.

When you open it up, it’ll look something like the following:

---
title: Hello World!
---

## This is the title of the page

and this is the content on the page.

A “document” in Jekyll is split into two sections:

1. the front matter (everything between the two --- lines)

2. the content (everything after the second ---)

Front matter provides a way to configure an individual page in your site. Again, it’s YAML because Jekyll uses YAML configuration. The content on your page is (usually) written in Markdown. If you’re not familiar with Markdown, there are several “Markdown cheat sheets” out there (e.g. this one).

One key concept in writing Jeykll pages is that you can “insert” any values set in your front matter in the content of your page. For example, to access the title variable from the example above:

This page's title is {{ page.title }}.

Anything between {{ and }} gets evaluated when a page is built, so the page would end up looking like:

This page's title is Hello World.

If you make any changes to your content, you should be able to go back to the live preview, reload the page (if you’re not using --livereload), and see the changes immediately. If they aren’t showing up, check your terminal to make sure there aren’t any errors in your markup.

You can put any values in your front matter, but some of them have specific meanings to Jekyll:

Every single page in the template website is a Markdown file very similar to the one you just edited. This is very powerful—if you see something in the template website you like, you can see exactly how it’s done by looking at the source Markdown file (you can do the same with the source to this site too).

Template Website structure#

The Template Website has 6 tabs in the menubar at the top of the page. These are (just like the old theme) called _collections: lectures, labs, assessments, resources, and news. Each collection has an associated folder: _lectures, _labs, _assessments, _resources, and news. These folders contain the actual content for each tab, including the corresponding index.md file that builds the landing page for that tab.

There is an additional tab in the menubar at the top of the page: help. This tab though is not a collection, as it links directly to a file called getting-help.md, rather than a folder.

The news collection works differently because it pulls posts from the _posts collection to display using the index.html file inside the news collection. Thus, since news only contains an HTML file and no md files, it is included directly in the website as-is (i.e. isn’t parsed by Jekyll) and so does not start with an underscore.

The remaining folders are theme and jekyll specific.

Deploying your website#

Before your website can be published, there is one more manual step to complete. Contact the Computing Facilites Team team and inform them that you have thoroughly tested and confirmed everything is functioning correctly in your local environment and that the CI/CD pipeline is passing.

The Computing Facilites Team team will then add an nginx proxy pass configuration that redirects from comp.anu.edu.au. With this in place, every time you run git push to your repository, your project will automatically be updated https://comp.anu.edu.au/courses/compXXXX after a few minutes..

You can do this as many times as you like—it’s expected that you (and others, e.g. your tutors) will be regularly updating the website through the semester. Still, remember that you can preview your changes locally before pushing them up, so you don’t need to push the site live just to see if it looks ok—that’s what the jekyll serve command is for.

A note on being a good citizen#

One final thing: using this Jekyll platform widely in CSS (e.g. for School websites) is an experiment in giving more control “back to the users” (i.e. School members), but there will be some workflow tweaks required as we figure out how best to do it.

In terms of the website repo editing stuff, some rules we’re trying are:

• avoid merge commits, for reasons articulated here, here and here—avoiding accidental merge commits is much easier if you set git pull to rebase by default with:

  git config --global pull.rebase true
  

• don’t commit large files² (let’s say > 1MB) to any of the School websites (we’ll look to enforce this in a pre-commit hook at some stage)

• we reserve the right to revert any bad-faith commits and revoke privileges as necessary (we’re not anticipating this, but it’s worth being clear about anyway)

• Your patience (and even input) is appreciated as we figure out a process which works for everyone :)

Next steps#

This is all just a starting point—you’re expected customise the content (and even the overall structure) as it makes sense for your webpage’s purpose. For some pointers on what’s possible, look at the docs page.

You’re now ready to set off and start editing your site. We’ve most of the basics here, but you can go much deeper: check out the docs section.

Remember—even after you git push to your GitLab project, your website won’t be live at https://comp.anu.edu.au/courses/compXXXX/ (or some other place if you aren’t making a course page) until you get in contactwith the help desk again so they can flick some switches and put it online (as mentioned above).