How to Contribute: Project

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 QuaRCS Bolivia. 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

The mission of QuaRCS Bolivia is to allow researchers and university students to easily access and contribute to the Bolivia geographical dataset.

There are several key terms:

• Dataset - A geographical dataset that is provided by the project for analysis. Here, the dataset is the Bolivia dataset.
• Topic - A grouping of related features within a dataset for analysis, which currently are Sustianable Development Goals (SDG). 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 reason for the distinction between a topic and a SDG is to demonstrate extensibility - the topics don't have to be SDGs, and can be extended as necessary to adjust for new categorizations.

QuaRCS Bolivia 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 topics. (This isn't to say that this project can't be extended to allow users to do this too. This would just require some further documentation on those processes).

Technical Breakdown

QuaRCS Bolivia primarily depends on Hugo, 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 generic, and 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. This site here is a good start: https://cloudcannon.com/blog/the-ultimate-guide-to-hugo-sections/

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

QuaRCS Bolivia uses Netlify to auto-deploy the Hugo project and receieve deploy previews on PRs. This process was achieved via The hugo-quickstart repo with a one-click deploy setup. Email dssd-madison@dssdglobal.org if you would like to learn more or contribute to the Netlify configuration.

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?

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.