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 bannername
: name of this server (capitalised, hostname only)href
: link to this server's README (typically justhttp://<hostname>.hacksoc.org/
).
nav
: links for navbartext
andhref
: fairly self-explanatory
Written in Markdown. Like regular pages, has a YAML header:
hostname
: lowercase hostname of the serverfqdn
: 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.
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 git@github.com: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.