This repository hosts the source material and code for the newest version of the MGAPS website, visible here.
The MGAPS website is built from source files by a compiler, mgaps-website
.
This compiler takes source material and turns it into a static website, automating as many tasks as possible for easiest maintainability. The resulting website works on both desktop and mobile.
If you have any questions, feel free to raise an issue.
The mgaps-website
compiler expects certain things from your website source. You need at least:
- A
static/
directory, containing static website content;- A
static/quick-links/
directory containing quick links information;
- A
- A
template/
directory containing HTML templates; - An
image/
directory containing images;- An
image/profile/
directory containing profile pictures;
- An
people/council/
andpeople/officers/
directories containing profiles (more on this later);js/
andcss/
directory containing the appropriate files;
While most content handled by mgaps-website
is in the Markdown format, the front page index.html
is a mix of HTML and Markdown to allow for easier layout control.
This is where you will edit the pages within the website. The pages can be found under the static/
directory.
Static content is written in Markdown format. Using this format, you have access to many features, including links, images, bullet lists, tables, code blocks, quotes, and many more.
To update a static page, simply edit the source Markdown file. mgaps-website
will compile Markdown source to HTML during compilation.
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. - contact (optional): the
contact
field specifies what MGAPS VP or officer is responsible for this page. This field must match at least one of the VPs or Officers. Contact information will be automatically added to the page.
Here's an example:
---
title: Test Page
contact: President
withtoc: yes
tocdepth: 4
---
# Level 1 heading
mgaps-website
will automatically create a webpage called people.html
based on the content of the people/council/
and people/officers/
directories.
The files in these directories should all be Markdown files with the following metadata:
- name (required): Person name;
- email (required): email address;
- position (required): Position within MGAPS. If a person holds more than one position, many profiles will have to be created.
- picture (optional): path to a profile picture, usually of the form
images/profiles/something.jpg
.
The body of the file is anything that will appear as profile description. Here's an example of a profile:
---
name: My Name
email: my.name@domain.com
position: VP Academic
picture: images/profiles/ny-name.jpg
---
As the VP Academic, it is my job to contribute to a positive academic
experience for MGAPS members.
The name of the files is completely irrelevant. Profiles can be added by adding a new markdown file. The distinction between people/council/
and people/officers/
is only so that the people.html
is easier to navigate.
Profiles NOT IN people/council/
or people/officers/
will be ignored.
An anchor is automatically created for every profile. For example, a profile with position: President
can be reached at the location people.html#President
, while a profile with position: VP Academic
can be reached at location people.html#VP Academic
.
In case where there are two positions with the same name (e.g. two PGSS representatives), the anchor will be placed on the profile that comes alphabetically first.
The front page index.html
has five quick links. These links are specified in Markdown files, in the static/quick-links/
directory, with the following metadata:
- title (required): Title of the quick link
- link (required): Link to the resource
An example of a quick-link file is presented below:
---
name: McGill Society of Physics Students
link: http://msps.sus.mcgill.ca/
---
McGill's offical organisation representing the undergraduates in physics
The name of the files in static/quick-links/
directory are not important. However, strange things might happen if the number of quick links changes to anything else than five.
Files can be hosted on this website, as long as they are stored in the files/
folder. Any file in this folder will be included in the website as-is. These files can be linked to from any Markdown file using the link syntax, for example:
...
The GA minutes are available [here](/files/ga_minutes_2018.pdf)
...
Images must be stored in the images/
directory. 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.
I urge you to use JPEGs as much as possible, especially for pictures/photos, as the compression pipeline in mgaps-website
is very space-efficient.
For ease of use, the mgaps-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.
mgaps-website
will generated the layouttemplates/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; - The order of profiles in
people.html
. For technical reasons, the only guaranteed order is that the President comes first.
Building the mgaps-website
compiler requires the Haskell stack
tool, which will install all dependencies. To build the compiler, run stack install
from the same directory where mgaps-website.cabal
and stack.yaml
are located.
The mgaps-website
compiler is a command-line program with a few options. An overview of the available commands is available as follows:
> mgaps-website --help
Usage: mgaps-website.exe [-v|--verbose] COMMAND
mgaps-website.exe - Static site compiler created with Hakyll
Available options:
-h,--help Show this help text
-v,--verbose Run in verbose mode
Available commands:
build Generate the site
check Validate the site output
clean Clean up and remove cache
deploy Upload/deploy your site
rebuild Clean and build again
server Start a preview server
watch Autocompile on changes and start a preview server.
The most useful command is build
, used to compile the website source into a built website:
> mgaps-website build
Initialising...
Creating store...
Creating provider...
Running rules...
Checking for out-of-date items
Compiling
updated templates/default.html
(... omitted ...)
updated static/workspace/fridges.md
updated sitemap.xml
updated static/index.html
Success
This command will update the last built website version into a folder called /_rendered/
. The compiler will only look at items that have changed; to trigger a rebuild from scratch, you can use mgaps-website rebuild
.
Once the website has been built using mgaps-website build
or mgaps-website rebuild
, the rendered website can be checked for common mistakes (such as nonexistent links) using the check
command:
> mgaps-website check
Checking file _rendered/workspace.html
(... omitted ...)
Checking file _rendered/finances.html
Checking file _rendered/events.html
The rendered website should be checked before publishing!
Deployment of the website is automated.
Simply commit the changes to the website source (in static/
, people/
, etc.). Once changes on the master repository are detected, the following will happen:
- A build server (provided by GitHub) will clone the content of the website;
- the Haskell toolchain will be installed;
- the compiler
mgaps-website
will be built; mgaps-website
will be used to render the website in_rendered/
- the changes in
_rendered/
will be committed to appropriate branch.