Home page for UTMIST.
Get familiar with the following language/framework/toolchain:
- HTML + CSS (no JavaScript on the Frontend)
- Pug, a templating language
- Node.js, for building the site and continuous integration
- We exclusively used
Yarnfor node package management. - TypeScript, type-checked JavaScript
- Google Sheet API + Google Drive API, as a CMS/PseudoDatabase
- Travis CI, a continuous integration service used here to build websites when the data change
- Make sure node.js and yarn are installed. Some Debian/Ubuntu versions may have
npmas a prerequisite foryarn. - Clone the repository,
cdinto the root. - Install packages by running
yarn. - Upgrade packages if necessary by running
yarn upgrade. - Use a static server of your choice to serve the repository, navigate to
index.html - To compile
.pugtemplates in watch mode, runyarn start. - To compile the templates just once, run
yarn build.
- Events/Execs: update the corresponding Google Sheet or use the Google Form, Travis CI will automatically update the site daily
- Other components: find the corresponding resource in the repository, make changes and commit
- One simple page/component
- Add a new
.pugfile in the repository root- If the file describes a complete page (starts with <html>), just compile after you are done, you should see a new
.htmlfile with the same name as the.pug - If the
.pugfile is a component, include it in the existing.pugfiles and compile
- If the file describes a complete page (starts with <html>), just compile after you are done, you should see a new
- DON'T DIRECTLY EDIT THE HTML, they are generated from
.pugand will get overwritten daily
- Add a new
- Self-contained sub directory
- Create a sub directory in the repository root (e.g.
new_site) - Put all your files in there, treat it as a separate static website
- Remember to serve from the root and navigate to
localhost\new_site\, because Github will serve the page withutmist.github.io\new_site\
- Create a sub directory in the repository root (e.g.
assets\: static assets such as images, video, large textcommon\: components used to stitch together a web pageFonts\,Log\: website brandingdatabase\: JSON copies of UTMIST data, fetched from Google Sheets, used by Travis to generate the site. It is not really a database, but acts as the source of "business data".files\: files referenced by thedatabaseindex.css,index.html,index.pug: entry point when users visit utmist.github.ionode_modules\: packages downloaded by npm or yarn. Not tracked by git..nojekyll: Github by default tries to build the repository with Jekyll, but our site is totally static, turning it off speeds up deployment (almost instant).travis.yml: configures how Travis builds the site, please put security tokens in Travis environment variables instead of herecompile.js: load in data fromdatabaseand compiles.pugfileswatch.js: compile on file change, useful for developmentfetch.js,fetch.ts: grabs info from Google Sheet and Google Drive and dump intodatabase\andfiles\, used by Travispackage.json,yarn.lock: file used by yarn/npm to track dependenciestsconfig.json: tells TypeScript how to check and compile.tscode
The build process is designed to minimize the manual house-keeping of the developer. For frequent changes such as adding events and adding members, Google Sheet API & Google Drive API pull the changes into the repository automatically. This process is run by Travis.
graph TD;
Daily --> Google
Dev("Commit to dev branch") --> Google
Google("Google Drive & Sheet") --fetch.js--> Repo("dumped in database, files")
Google --fail to fetch--> Nochange("Not built")
Repo --compile.js--> Built("Generated HTML&CSS")
Repo --fail to compile--> Nochange
Built --> Github("Github Pages")
Remember to put Google API tokens and Github tokens in Travis environment variables, not in plain text anywhere in the repository.