This repository contains the source code for the TBRe website. The site is built using Jekyll, uses a Bootstrap 3-based theme called Agency, is deployed via Git and hosted on GitHub Pages within our team GitHub Organisation. It is reached via our custom domain, teambathracingelectric.com, registered at Namecheap with CDN and SSL provided by CloudFlare.
Providing instruction on the use of every tool needed is beyond the scope of this readme but links to documentation are provided for reference where appropriate.
This section explains how to set up the necessary environment to get a local copy of the site that can be edited. The best way to set things up will depend on what sort of computer you're using:
bash
apt
Before going any further, you will be required to be familiar with the basics of Git and Jekyll. Links to documentation can be found above
The website source code lives in a repository (repo) on GitHub. This particular repo belongs to the Organisation set up for the team. Anyone in the organisation can view the repo, but only members of the Website team have write access. Membership of each is invite-only, so create a GitHub account and provide your username to someone who can invite you. So:
(NB: Changes can be made to the source code directly on GitHub without going through any further steps but you can't check your edits before deploying them so this is only really viable for small tweaks and changes that you are 100% sure won't break anything)
To work on the repo properly, you need to clone it. This means use Git to download a carbon copy of the source code which you can then commit changes to and reupload (or push) when you're done.
First you'll need Git. By default this is a command line tool and can be downloaded here or by asking BUCS. A more beginner friendly GUI alternative is the GitHub Desktop app. Then clone the repo using commands such as:
$ cd ~
$ mkdir GitHub
$ cd GitHub
$ git clone https://github.com/teambathracingelectric/teambathracingelectric.github.io.git
This makes a new folder in your home directory and clones the repo into it. If you're using WSL, you'll want to cd
to your Windows home directory instead (/mnt/c/Users/[username]
) To check if it worked:
$ cd teambathracingelectric.github.io
$ ls
The easiest way to work on the site is to use a programming text editor with project support like VS Code. Open the repo folder in the editor and you should get the whole website structure show in the sidebar. Listed below is what each part of the website source is for:
default.html
is where the html sections are all put together, compress.html
is a filter to compress the site htmlChanges to the site can typically be done in one of three ways:
NB: This site uses the Bootstrap 3 framework. Using BS3 elements and tools when making changes to the site will both save time and keep the site looking nicer.
After making the desired changes to the site, you should check to make sure it works as expected before pushing it to the website. This is when you will need to make sure the required tools are installed:
WSL:
$ sudo apt install ruby
macOS:
$ brew install ruby
And then in the site directory:
$ gem install bundler
$ bundle install
With the tools now installed you can use rake serve
to run a live testing server showing a local version of the site. If the changes are as desired you can now push them to the site
The site repo has several git branches. It is recommended to use them properly to keep things organised. Work on the site using the dev
branch or alternatively create a feature branch if working on a particular feature and merge into dev when complete. When you are ready to deploy your changes, merge dev
into the source
branch. Try to keep the source
branch production ready at all times (i.e. only merge commits that you know don't break anything) otherwise you risk pushing bad code to the actual website. Use the git push
command to push the source branch back to GitHub. This gets picked up by Travis, which builds the site and deploys this to the remote master
branch which is where our domain actually points to.
So the general workflow:
rake serve
source
branch and merge the dev
branch into it.git push
to push source
to the GitHub repoNB: VS Code provides a useful UI for many of the Git functions used above. Ctrl+Shift+G opens the Source Control Panel and the icons at the bottom left of the window represent the active branch and remote repo status.
There are two relevant things to note. First, you can use rake test
to run some basic tests on the site code, including checking html validity and whether any external links are broken. Second, Travis runs this test when it builds the site and if any tests fail, it will refuse to deploy so make sure the tests pass before pushing your changes
Coming soon.
See also the list of contributors who participated in this project.
This project is licensed under the Apache 2.0 License - see the LICENSE.md file for details