Skip to content

How to Contribute: Project

Jump to bottom
Geoffrey Xue edited this page Sep 10, 2023 · 7 revisions

Not interested in contributing to the project code and instead the stories? Check out the above link on stories instead.

This page will provide information on how to contribute to the University Student Accessible Research Database (USARD). This will first cover a high level overview of the project itself, and then go through a technical breakdown.

It is useful to examine the project while reading this information. To get the project running locally, check out the latter half of the README provided at the root of this project.

High Level Overview

USARD Context and Breakdown

The USARD project aims to be a database with a collection of geographic datasets related to sustainable development across subnational regions and countries.

There are several key terms related to the USARD project:

  • Dataset - A geographical dataset that is provided by the project for analysis.
  • Topic - A grouping of related features within a dataset for analysis. A dataset has a collection of topics.
  • Stories - A investigation performed under a topic using the related features (or potentially other features as well). A topic has a collection of stories.

The USARD project enables interactivity via its stories - users, and particularly university students, can gain insights from details under each topic as well as other stories. They then can contribute their own stories themselves.

As of current, developers introduce the datasets and topics. (Note: However, this isn't to say that this project can't be extended to allow users to do this too. This would just require some structural changes and further documentation on those processes).

Technical Breakdown

The USARD project depends on Hugo primarily, a static site generator framework. There are some key features of Hugo that are used for the project to make it easy for users to contribute stories.

Note: Hugo is both complex and made generic, often has many ways to do one thing. The existing code hopefully self-documents practices that are followed within the project. The Go templating that Hugo relies on can be pretty hard to follow, so it may be valuable to look at an independent introduction to Hugo.

Some key features of Hugo:

  • Content - /contents/ contains Markdown .md files that include not only the structure of the project that determines the URL file paths, but also also all of the stories and their related resources. Story folders under a topic can be located under /contents/topics/{topic}/stories/*
  • Layout - /layouts/ contains HTML .html files that format the content markdown files. The information related to markdown files and other formatting is done with Go templating
  • Partials - /layouts/partials/ contains HTML .html files that are reusable throughout the layout via Go templating by adding {{ partial "partial-name" .}}
  • Shortcodes - /layouts/shortcodes/ contains HTML .html files that are reusable within the content. This allows users to use custom-built blocks made for the stories, which aids in formatting/embeds/images
  • Static - /static/ contains static files that are copied to the generated site, which contains JavaScript .js, CSS .css, and the datasets. Files with paths like /static/something/... become https://.../something/... on the site

The USARD project uses Netlify to auto-deploy the Hugo project and receieve deploy previews on PRs. This process was achieved via Netlify's automatic framework detection upon importing project.

Below is an FAQ of some general questions to better understand how Hugo operates.

Why do the stories (and its resources) not have a file path, but everything else does?

image

This is related to page bundles and page resources. For each directory within the project, if a _index.md is specified, the directory allows nesting of other bundles. If a index.md is specified, that directory is a leaf bundle instead, and any other files below it are considered resources. Since each topic has a index.md at its directory, the story folders and its contents are all considered resources.

How do you know which layout file formats which content file?

The layout file is chosen based on the content file type. The type can be manually specified (as it is for an individual topic), or left empty, in which case its directory path from content. Hugo then looks for a folder in the /layouts/ folder that matches it, and uses either a index.html or a list.html, depending on whether an index.md or a _index.md was used.

Clone this wiki locally