Home

These docs in this wiki are meant as a guide for future developers and maintainers of the site, from the person who originally who built most of it.

If you're new to the site, I'd recommend reading through all of these docs in their entirety (if you have the time). If you've got experience with static sites though, then you can probably just skim to the section you want (or not even bother reading this at all!).

These docs should be kept up to date as major changes are made to the site.

Content editing

Probably the most common regular operation on the site will be to write new newsletter posts, and modify the site's pages to be up to date.

To facilitate this very common operation, the site uses Netlify CMS at cssbham.com/admin. Essentially, it provides a fancy web user interface to the repository. All of the information that's presented on the admin portal is only gathered from the GitHub repository, which is effectively the source of all truth.

To access the CMS, go to cssbham.com/admin, where you'll be presented with a login screen. Note that you shouldn't need to be a member of the CSS GitHub organization to login, though you might need to be to actually save your edits.

IMAGE

Click the login button, and you'll be asked to authorize the CSS admin portal application, if you haven't already. If at any point you want to revoke permissions for the app, you can do so in your Github Application Settings.

Once you've logged in, you'll have access to the admin portal. There are 3 main views; Contents, Workflow, and Media.

Contents

The contents tab is where you'll have access to modify all of the site collections. There are a number of collection types, however, under the hood they are all represented as markdown files with some additional fields.

Inside a collection, you'll have the ability to view and edit all existing items in the collection as well as create a new item.

The editing interface for individual items can be slightly confusing. On the left, you can edit the actual page content, while on the right, you can see a live preview of what it should look like. These are not accurate of what they will actually look like (there may be a way to make them actually accurate, but I'm not sure how, and haven't looked hard into it).

Each type of content in a collection is different - for example, clubs are different from posts, which are different from pages. However, all of them should have a title and a block of markdown content. Try and fill in all of the available fields if you can.

Side note: sometimes when adding content, it can be difficult to work out which type of content is most appropriate. To get an idea, look at the types of content in each category and work out which it's most similar to. As a general rule, pages linked to a specific date and time should be a Newsletter, general information should be a Page, and any workshops/clubs should be a Club.

Workflow

When you make changes on the Netlify CMS, and you click save, they're not immediately put onto the live site. Under the hood, they're made in to a GitHub Pull Request. This is so that other members of the committee have a chance to weigh in and review your changes before they go live.

The Workflow tab gives you the ability to see an overview of all of the waiting changes that haven't been fully approved. This is a super handy way to see what other people have been working on, as well as allowing different committee members to make different changes across the site without walking all over each other.

You can change the status of the PR and move it between the Draft, In Review, and Ready states (though they don't really have any influence, and are just useful labels).

Once you're ready, you can publish your changes by clicking the Publish button. Note that you won't be able to do this unless someone has approved your Pull Request (this is enforced by branch protection in the GitHub repository settings).

Media

The Media tab lets you upload images, videos, etc to the site that you can use them in your site content. To reference an asset from markdown, prefix the filename with /assets/images/. So if your image name is "abc.png", reference is using the URL "/assets/images/abc.png".

Manual site changes

Sometimes Netlify won't cut it annoyingly, it can't do everything. So for everything else, you'll have to dip into the code itself. It's also worth having a look at the code that Netlify CMS produces automatically, as sometimes it can be a bit strange, and not perfectly formatted and such.

The site itself uses Jekyll, so it's definitely worth getting to grips with it before you try and make changes, the official site at here has fairly good documentation.

Jekyll uses the Liquid templating language to help with building more complex setups. You shouldn't use it in your collections if possible, but it's completely invaluable when building new layouts.

This section isn't a tutorial on using Jekyll, as there's already great resources for that (like linked above), but more of a description of how this particular site it laid out.

Pages

You can identify pages by the fact that they're just sitting around in the root directory, with filenames ending in .html and .md. When creating a new page, you should always prefer using markdown over raw HTML whenever possible, it's just way easier to read and maintain. However, don't be afraid to use raw HTML if markdwon won't do.

All pages (and all other items in collections) need to have frontmatter in them. This frontmatter corresponds to the extra fields as seen above in Netlify CMS.

All frontmatter should include, at the very least, a layout and a title.

Other useful fields that might be handy are styles (for including additional CSS for only this page), and scripts (the same, but for scripts).

---
layout: page
title: Committee
styles:
  - /css/committee.css
scripts:
  - /js/fadein.js
---

The main page content uses Markdown, a really powerful and fun markup language, that makes writing text easy. It's not too hard to get the hang of the basics. Additionally, it can also contain raw HTML, which is very handy if you're building more complex layouts - however, use this ability sparingly, and always prefer native markdown elements over HTML ones.

Collections

The collections for the site, are intuitively located in the collections directory.

collections
├── _clubs
└── _news

All of the content in these works pretty much identically to the pages from above, however, within a single collection, all items should all aim to look as similar to each other as possible and use the same layout wherever possible.

Redirections

Settings up short links is lots of fun, and makes us look extra professional. They're implemented using a ridiculous hack that I'm super proud of, but it's the best we can do without moving hosting provider.

To add a new redirection, add a new entry to _data/redirects.yaml, for example:

- source: /facebook
  destination: https://facebook.com/groups/CSSUoB

Note that these redirections are resolved at a Javascript level, not at an HTTP level. Therefore, they won't work with Javascript disabled, and won't be indexed by search engines.

Site wide config

Site wide config settings can be found in _config.yml. These contain configuration for all the pages on the site, such as menus, the site name, the base url, etc.

Netlify CMS config

Configuring Netlify CMS can be done from admin/config.yml. This file will let you configure the behaviour of the CMS editor, and the collections that they can modify from that interface.

You probably shouldn't need to modify this that much unless you're making sweeping changes to the collections or frontmatter definitions - in that case, make sure you update the config to reflect that.

Committee data

In the data/ folder you can put any site-specific data. One interesting item there lists the current committee for the /committee page.

To update to the new committee, you'll need to update these files. Don't overwrite the existing ones, instead make a copy and name it according to the academic year that the committee will preside over. Follow the exact same format that's already defined, and update the current value to be true (and also modify the old committee values to be false while you're at it).

You'll probably also want committee photos. You need to crop them beforehand to be square, or you'll get weird results. You can put them anywhere, but in practice you should put them in /assets/committee/<years>/full/.

Then, run _scripts/committee.sh (on a Linux system) to generate the mini images that are more optimized for loading on the web.

Site architecture

The setup for this site is quite straightforward, and if you have any experience with Jekyll-based sites, you'll fit right in.

A few important files and folders that you should be aware of:

• _config.yml
  • Site-wide configuration
• favicon.ico
  • Little image displayed in the corner of tabs
• _data/
  • Contains data accessed by pages to render content
  • Deciding whether data should go here or into frontmatter directly can be a tricky decision, prefer putting it into page frontmatter unless multiple pages need to access the data.
• _collections/news/
  • Contains markdown files for each newletter post
• _collections/clubs/
  • Contains markdown files for each club
• _assets
  • Location for all static assets
• css
  • CSS and SASS files that make up the stylesheets for the site
• js
  • Javascript used in the site
  • Use sparingly, we want the site to still work for people who don't enable Javascript
• fonts
  • Fonts used on the site
• _layouts
  • Define the general structure of pages
  • Can inherit from each other to form hierarchies (super useful to avoid repetition)
• _includes
  • Utility "functions" for layouts (and also for individual pages)
• _scripts
  • Assorted collection of scripts for developers to help them make changes to the site

There are 3 layouts that you might want to use.

• page
  • The most basic of layouts, a normal page that can contain any content
  • You usually do not want this one, unless you're making a new page entirely from scratch, it's very plain and basic
• textpage
  • A slight alteration of the page layout to emphasise text and make it look nicer.
• post
  • The layout used in newsletter posts.

Deployment setup

Our development/deployment setup is a little scattered, like all setups out there, but it means you'll need to access a variety of services to do things.

• Source control: GitHub
  • All of our code is hosted on GitHub
  • If you're not familiar with Git, definitely try and learn it
• Hosting: GitHub pages
  • We use the GitHub default, GitHub pages
  • It automatically builds the Jekyll site and deploys it (and listens on the domain name) in the CNAME file
• CI/CD: GitHub pages/Netlify
  • GitHub pages is used to deploy our production site
  • Netlify is used to deploy our branch previews (at <cssbham.netlify.app>(https://cssbham.netlify.app))
• DNS: Namecheap
  • The domain name is owned by Tom, so if you need new DNS records, bother him to do it
  • As long as we remain with GitHub Pages, we shouldn't need different records

There are a few accounts associated with all this.

• CSSUoB GitHub Organization
  • The group that we do all GitHub stuff under
  • Can have multiple members and fine-grained permissions for members
  • We have a few repos, namely, the site, and a few other resources
  • The organization owns the CSS Admin Portal OAuth App
• CSS GitHub Account
  • Super confusingly, we also have a CSS GitHub account
  • This is a bit of a hack to allow Netlify to access the CSS repos without being directly tied to an individual user's OAuth
• CSS Netlify
  • This account is used to access the Netlify settings and such
  • The Admin Portal OAuth settings are copied from the organization to here