hkazmi25/siwick-website

Compiler and public content for the Siwick research group website

siwick-website

• Overview
• The website source
• Updating pages
  • Updating the front page
  • Updating the People page
  • Updating static content
  • Updating images
  • What cannot be easily changed
• Usage of siwick-website
  • Installation of the Haskell toolchain (including cabal).
• Deployment

Overview

The Siwick research group website is a website generated by a program, called siwick-website. T.his program does a few things, but most importantly, it translates Markdown files (easy to write by hand) to HTML (not easy to write by hand).

The website source

The source material for the web pages are located in a few directories:

• static/: Markdown files corresponding to web pages which don't change often;
• people/: Markdown files corresponding to people within the Siwick research group, past and present;
  • poeple/students/: Files for students/postdocs currently in the group;
  • poeple/alumni/: Files for students/postdocs that are no longer in the group;
• images/ and vector_images/: Image files;

There are also some helper files for the siwick-website program:

• templates/: Templates are HTML files which control the appearance of the website;
• css/ and sass/: Styling for the website;
• js/: Small Javascript file to have an interactive navigation bar.

The siwick-website program takes files from the above directories and produces a website in the directory _rendered/, which is not tracked by git.

Updating pages

Updating the front page

While most content handled by siwick-website is in the Markdown format, the front page static/index.html is a mix of HTML and Markdown to allow for easier layout control.

Updating the People page

The people page is special because it is autogenerated based on the files in people/.

Adding a new student

Adding a new student is as simple as adding a new Markdown file to the people/student/ directory. The file should looks like so:

---
name: Alice Bob
position: Ph.D. Student
email: [email protected]
phone: [phone]
office: Otto Maass Chemistry Building, room 025
picture: /images/profiles/Alice.jpg
homepage: http://alicebob.com 
---

Alice has been performing some experiments on XYZ 

The position field must be one of the following choices: Postdoc, Ph.D. Student, M.Sc. Student, Undergraduate or International. The picture and homepage fields are optional.

Adding a new alumni

Once people leave the group, their associated Markdown file can be moved to poeple/alumni. The file must be updated to look like so:

---
name: Alice Bob
degree: Ph.D. 2022
email: [email protected]
date: 2022-06-15
picture: /images/profiles/Alice.jpg
---

Updating static content

Apart from the People page, most other pages are Markdown files converted to HTML. The syntax for Markdown is described here.

Static pages have metadata at the top. At this time, the following metadata is available:

• title (required): title of the page. This title will appear in the top banner.
• withtoc (optional): if withtoc: yes, a table of content will be automatically inserted at the top of the page.
• tocdepth (optional): Table of content depth. For example, if tocdepth: 2, level 1 and level 2 headings are taken into account in the generation of the table of content.

Example:

Here's an example:

---
title: Test Page
withtoc: yes
tocdepth: 4
---

# This is a new page

Updating images

Images must be stored in the images/ and vector_images/ directories. Subdirectories, like images/profiles/, are also supported. There are two cases:

• JPEG images (*.jpg and *.jpeg) are compressed automatically;
• Non-JPEG images are copied as-is.

Using JPEGs as much as possible allows for the siwick-website program to compress the website. Try to use them as much as possible for pictures.

What cannot be easily changed

For ease of use, the siwick-website compiler forces certain things to stay the same. These are:

• The overall page template cannot be changed. This includes navigation bar, top banners, and page footer. siwick-website will generate the layout templates/default.html automatically, and all changes to it will be overwritten;
• The website schema, or website map. Navigation links (visible in the navigation bar) are generated by the compiler. New webpages can always be added (in the static/ directory) but these webpages cannot be linked from the navigation bar unless the compiler source code is changed;

Changing the things above requires modification of the siwick-website source code in compiler/.

Usage of siwick-website

The siwick-website program is a Haskell program most easily compiled by the cabal tool (More on this later). The steps to use the siwick-website program are as follows.

1. Build and install the program using cabal build:

cabal install

2. Run the program:

cabal run siwick-website -- rebuild

3. Check that all HTML links are valid:

cabal run siwick-website -- check

or, for links within the website itself only (much faster):

cabal run siwick-website -- check --internal-links

Installation of the Haskell toolchain (including cabal).

It is recommended to install and manage the Haskell toolchain using ghcup. Once this is installed:

ghcup install cabal
ghcup install ghc

Deployment

Once the website is built, i.e. all the HTML files and other supporting files have been compiled into _rendered/, the directory _rendered/ needs to be deployed onto the McGill Physics department servers. This is done using the deploy.py script.

To use deploy.py, you need: * Python 3.7+; * paramiko; * tqdm;

You can install the dependencies paramiko and tqdm via the requirements.txt file:

python -m pip install tqdm
python -m pip install paramiko

Finally, to deploy the website:

python deploy.py