This repository contains the source code, content, and provides the hosting for the DAWN public website. Created by David Taylor
The website uses the open source Jekyll static site builder. GitHub provide a build system for their (somewhat restricted) distribution of Jekyll, called github-pages.
Anything in the default branch (gh-pages) will be served on the website. To make changes without affecting the production site, make sure you use a separate branch. Sometimes it can take a couple of minutes for GitHub to rebuild the site after any changes are made (you will also need to empty your browser's cache).
To make simple changes to the content, you can use the online GitHub editor. Just browse the source code and hit edit or new file to use the online editor. You can also clone the repository in the traditional way, and make changes using your favorite text editor.
Jekyll uses markdown to make writing rich content in a text editor easy. You can just write in plain text, but for rich styling, an overview of the syntax can be found here.
For hiding email address in mailto anchor tag, generate XOR pairs for mailto: and the email address with the encode.py script then
use the template:
{% include email.html m='mailto-xor-pair' a='email-address-xor-pair' %}
For YouTube video embeds, use the provided template by typing:
{% include video.html url='https://www.youtube.com/embed/zdIMHYyqdcQ?list=PLBXR5FtaBSTT7DXBx6p0v9u8fwQTwlPFa' %}
Replacing the URL with the embed url of the video
Images and other files should be committed into the /assets directory. To embed an image, use the syntax:
To add an automatically generated table of contents (based on heading levels), type
Unordered Table of Contents:
* TOC
{:toc}
Ordered Table of Contents:
1. TOC
{:toc}
There are two types of content on the website. Pages and Posts. Pages are displayed in the menu on the left, while Posts are entries in the "News" section. Pages are stored in the _pages directory, while Posts are stored in the _posts directory.
Pages do not have a fixed file name format. However, they are loaded into the menu in alphabetical order, so it is sensible to follow the format
##_page_name.md
where ## is a number with leading zero. Sub-Pages should follow the format
##.%%_page_name.md
where %% is a second number defining the page's position in the sub menu.
The file extension .md indicates a markdown file. You can also use html files, but for normal content .md is easier to work with.
At the top of every file there must be some "YAML Front Matter". This contains meta information about the page. It it delimited by three hyphens --- above and below, and follows a key: value format (remember the space). Pages must provide values for title and permalink. For example:
---
title: Contact Us
permalink: /about/contact-us/
---
title:is displayed in the menu, and at the top of the page.permalink:is the URL of the page. Must be unique, no more than two levels, and any parents must have existing pages (in this case, theaboutpage).
Underneath the front matter, the content for the page should be written in markdown format.
Posts must follow the defined file name format
YEAR-MONTH-DAY-title.md
where YEAR is a four-digit number, MONTH and DAY are both two-digit numbers.
The file extension .md indicates a markdown file. You can also use html files, but for normal content .md is easier to work with.
At the top of every file there must be some "YAML Front Matter". This contains meta information about the page. It it delimited by three hyphens --- above and below, and follows a key: value format (remember the space). Posts must provide values for, title only. For example, a file 2026-08-12-dawn_10_release.md could have front matter:
---
title: DAWN 10.0 Release
---
title:is displayed in the menu, and at the top of the page.
Underneath the front matter, the content for the post should be written in markdown format.
The most recent post will be displayed on the home page. Other posts are visible in the list on the /news/ page.
To preview your changes locally before deploying to the production website you need to run the Jekyll Ruby gem. Instructions to do this can be found here. A Vagrant virtual machine definition is included in this repository to avoid the need to install Ruby on your development machine.
Use Docker or podman to build and serve site locally (avoid jekyll:4.2.[12] as image needs webrick which is missing in Ubuntu 22.04)
$ docker run -it --rm --publish 8080:4000 -v $PWD:/srv/jekyll:Z jekyll/jekyll:4.2.0 jekyll serve
and wait for the "Server running... " message then go to a web browser and visit http://localhost:8080.
- Download and install Vagrant. It is available for most operating systems. The installer will prompt you to install virtualbox.
- Clone this git repo to a local folder
git clone https://github.com/DawnScience/dawn-website.git dawn_website
- Change directory to the local folder
cd dawn_website
- Start the vagrant virtual machine.
vagrant up
- Get a cup of tea while you wait. This command will take a long time the first time you run it, as it needs to download a linux virtual machine image and install all necessary dependencies.
- Once it's finished, go to a web browser and visit
http://localhost:8080. You should see the website
Go back to your terminal (inside the repo directory) and type:
vagrant ssh
less -S +F ~/jekyll.log
To stop looking at the log press ctrl+c, type :q, then type exitenter
This is useful if you update the _config.yml file, or the Jekyll compiler crashes:
Go back to your terminal (inside the repo directory) and type:
vagrant reload
Go back to your terminal (inside the repo directory) and type:
vagrant halt
To completely destroy the virtual machine image, use
vagrant destroy
This will not delete any of the source code or content. If you do this, you will have to do a full re-install when you next do vagrant up
Everything is in GIT - just revert the change that you made