Skip to content
This repository has been archived by the owner on Aug 22, 2018. It is now read-only.

Home

Jump to bottom
Joseph Gilby edited this page Jan 9, 2018 · 11 revisions

This wiki contains some basic documentation on how to use or edit the website.

Technical Information

The website is set up using the Hakyll static site generator, which is written in the Haskell programming language. The site.hs file contains the code for our site. So, the steps involved in actually generating the site are:

  • The site.hs file has source code which uses the Hakyll library & EDSL to implement our own static site generator. There are clauses in this file that specify (1) for every input file, how to create an output version of it and (2) for every ad-hoc-generated file, how to generate it from the other available information.
  • Running stack build will produce an executable site from site.hs, which is a compiled version of the static site generator. This does not actually produce the site.
  • Running the site executable that was generated a second ago is what actually generates our site: following the instructions in site.hs, it reads in all of the input files that have been identified and writes out whatever output files need to be modified.

Since we have a mirror of the site set up on github pages, the master branch is reserved for the build static version of the website. All of the website sources are on the hakyll branch, and this is where all changes should be made. Whenever changes are pushed to GitHub, our CircleCI builder builds the website and, if the build is successful, deploys it.

If you want to get a local copy of the website, here is the all-in-one list of commands to run; the only major dependency is the Haskell tool stack:

git clone https://github.com/UCSD-SUMS/web.git
cd UCSD-SUMS.github.io
git checkout hakyll
stack build
stack exec site watch

If you do not have the correct version of the Glasgow Haskell Compiler installed, the command stack setup will install it into a project-specific directory.

If you make changes or add any event files, the site will be automatically rebuilt and your local webserver will serve an updated version of it. However, if you change the website logic in site.hs, you must stop the site watch and re-run the stack build and stack exec site watch commands.

Windows

These instructions are only known/tested to work on Linux systems. There are some known issues on Windows systems:

  • https://ghc.haskell.org/trac/ghc/ticket/10762 appears to document an issue that affects windows builds, with a workaround mentioned in the issue: it has been reported that using the command chcp 65001 before running site builds fixes this.
  • It is possible that dynamically recompiling the site whenever files change may not work, although it has been reported that this is actually caused by the above point and goes away with the workaround applied. In any case, if this is a problem, it is best to run stack exec site build instead of stack exec site watch, which does not require you to kill the process before restarting it manually after file changes.
  • It has been reported that Cygwin can suppress some error messages and cause other problems while building the site. It is recommended that the site executable be run from inside cmd.exe instead.

Basic editing/updating

This section describes the process for making basic edits/updates to the website. All of the edits performed below could be performed on a local git checkout (see above) or through the GitHub web UI:

Creating an event

To create an event, create a new Markdown file in the directory events/<quarter>/, where quarter is the current quarter (e.g. fa16, wi17, sp17). The description of the event should be written in this markdown file in plain text. A special header block should be added at the top of the file with the following contents:

---
title: "Title Of The Event"
start: YYYY-MM-DD HH:MM:SS
end: YYYY-MM-DD HH:MM:SS
location: "Location Of The Event"
future: true
---

Marking an event as no-longer-future

If an event has already occurred but is still appearing on the front page of the site under upcoming events, the event file needs to be updated to show that this event is no longer in the future. The way to do this is to find the Markdown file with the source of the event (in general if the event web page is events/<quarter>/<name>.html, then the source file name is events/<quarter>/<name>.md) and remove the future: true line from the specially-formatted header block at the top of the file.

TODO: Add easy process & docs for other changes to site

Clone this wiki locally