This build system is based on Node.js and Handlebars. It replaces the previous system, which used Haskell and Hakyll.

See Installation Instructions to get set up. Please test your changes locally before committing.

As this includes the most recent news articles, editing the homepage is done through index.handlebars. The 5 most recent news articles are rendered via newslist.handlebars, then index.handlebars itself is rendered, and finally passed to wrapper.handlebars.

These can be found in regular/, and consist of a YAML header and a HTML body, which is inserted into the template wrapper.handlebars.

• title: put into the <title> element of the page.

Written in Markdown, with a YAML header:

• title: the title of the article, put into the <title> and <h1> elements and shown in the list of news articles.

The first paragraph of the article is shown as an excerpt in the news article list, Markdown requires a blank line (not just a single newline) to indicate a new paragraph.

For the moment, minutes are in PDF form and are put into minutes/. These are copied into the web directory, along with an index page which lists all the minutes in the directory. The filename format is YYYY-MM-DD-meeting name.pdf. Regular committee meetings are simply YYYY-MM-DD-Minutes n.pdf. The minutes page sorts these in ascending date order based on the filename, so omitting the date will cause this to fail.

Most of the site is generated through the wrapper.handlebars template. This takes the content of the page, the title, plus some global values found in templates/context.yaml:

• servers: controls the list of servers on the website banner
  • name: name of this server (capitalised, hostname only)
  • href: link to this server's README (typically just http://<hostname>.hacksoc.org/).
• nav: links for navbar
  • text and href: fairly self-explanatory

Written in Markdown. Like regular pages, has a YAML header:

• hostname: lowercase hostname of the server
• fqdn: full domain of the server, typically <hostname>.hacksoc.org
• name: purpose/subtitle of the server (eg "shell server")

Don't worry about a H1/title, it's generated by the template. All headings in the document should be H2 or below (##).

To keep a consistent style, the following rules are used:

• Line length: text in news/ should not exceed 70 characters per line (the odd 71 is okay). Otherwise, documents should NOT use hard wrapping, and instead use your editor's soft wrap setting to display long lines of text.

about.html contains information about the committee, including their current year of study. The year given should be the 'stage' that the committee member is in. When a member is on a year in industry, they should not be listed as being in any year and instead as "currently on year in industry". If the year in industry is in between stages two and three, they will return as a "third year".

More guides may be added so always check this section when authoring new content!

You'll need Node.js (with npm) to install and run this. Don't install Node.js from your package manager repositories, it's likely outdated.

$ git clone [email protected]:HackSoc/HackSoc.org

$ cd hacksoc.org/
$ npm i

$ npm start

This builds the site to the output folder html/, you need to run this command every time the content updates in order to keep the web version up-to-date.

$ npm test

This will start a web server on your computer and open a browser to index.html, so you can test that your changes work correctly.