Getting Started

Tech Stack

tutors-in-action.org is a static website hosted on GitHub Pages. The website is built using Hugo, a static site generator (SSG), and styled with Bootstrap 5. Aside from that, here is a non-exhaustive list of the technologies that you should be familiar with before getting started:

• Markdown, to write content for the website;
• npm, to manage JavaScript packages;
• jQuery, to simplify HTML DOM tree traversal;
• SCSS, to manipulate Bootstrap's variables;
• Python 3, to write scripts for automating tasks, e.g., downloading thumbnails and processing pdfs;
• and, of course, Git, to manage version control and collaborate with other developers.

Directory Structure

The repository is structured as follows:

C:.
│   .gitignore
│   .npmrc
│   config.toml
│   LICENSE
│   package-lock.json
│   package.json
│   postcss.config.js
│   README.md
│   requirements.txt
│   spider.py
│
├───.github
│   └───workflows
├───archetypes
├───assets
├───content
├───data
│       faqs.json
│       resources.yml
│       team.json
│       _resources_mapping.yml
│
├───layouts
│   │   404.html
│   │   index.html
│   │
│   ├───page
│   ├───partials
│   │       footer.html
│   │       nav.html
│   │
│   ├───shortcodes
│   └───_default
│           baseof.html
│           list.html
│           single.html
│
└───static

The structure follows Hugo's specifications. In short, here are some key directories and files worth mentioning:

Directory / File	Description
.github/workflows	Github Actions workflows for the repository. Currently there are two: one for deploying the website and another for managing thumbnails in the "resources" page.
archetypes	Default front matter for new content files. See the content folder.
assets	CSS files. The plugins specified in postcss.config.js will post-process those files before getting loaded into the HTML.
content	Markdown files: a file corresponds to a page on the website "projects" section.
data	JSON and YAML files that store data, e.g., the FAQs, resources, and committee structure.
layouts	HTML templates for the website. We will talk more about this in the future.
static	Files (basically images) that are copied directly to the root of the website.
config.toml	Hugo configuration file. A lot of the website text content is also here.
spider.py	A handy script that downloads thumbnails via the Google Drive API.

Setting Up

If you just want to view it locally, install Hugo and run:

hugo server

The website will be available at http://localhost:1313. Live reload is enabled, so any changes you make to the website will be reflected immediately.

Alternatively, run:

hugo

to generate the website artifact. The generated files will be in the public directory. These files are the ones that will be deployed to GitHub Pages.

To contribute to the website, you will need Node.js and install the required dependencies. Run:

npm install

This will install the required packages specified in package.json. After that, you can run:

npm run serve

or

npm run build

which are equivalent to hugo server and hugo, respectively.

To run the spider.py script, you will need to install Python 3 and the required packages specified in requirements.txt.

A Google API Key is also required. See this guide from Google on how to create an access credential on Google Cloud. Once you have your API key, set it as an environment variable named GOOGLE_API_KEY. Finally, run:

pip install -r requirements.txt
python3 spider.py

IDE

I personally prefer using JetBrains products, such as WebStorm (and PyCharm for Python). In case you are interested, you can get a free license by signing up for the GitHub Student Developer Pack.

You have to install the Smart Hugo plugin in Webstorm to allow the IDE to recognize Hugo's syntax. However, you may still see some lines marked red in the code of this repository, but the website will still build and run fine.