Below are the steps to contributing your own story to the site!

What is a Story?

A story is a blog post-like blurb written under a topic as an analysis of that particular topic and its relevant data features.

Check out some of the existing stories on the site: https://quarcs-bolivia.netlify.app/.

Drafting a New Story

Here are a series of steps to creating a story:

• Take the data here and explore! Or, if you have a direction already:
• Consider an applicable topic and tags for the story. What is your focus for your story?
• Consider relevant features in the dataset.

We recommend exploring the dataset in Deepnote or porting your local changes to Deepnote; this will allow you to embed your code blocks on your site directly for your story.

Contributing Your Story

Once you have your story ready to contribute to the project, the main steps will be to:

1. Create a folder.
2. Add story metadata.
3. Edit story content.
4. Review and revise.
5. Add a reviewer and update your pull request!

0. Getting set up

You can either do this on your local computer or on a Visual Studio Code editor in your browser on Github by going to https://github.dev/DSSD-Madison/Nagoya. Just using the Github web UI is also possible, but will require some of the workarounds mentioned below.

1. Create a folder

From the root of the project, content/topics contains all of the topics for the data. To create a story folder, create a folder under the topic that you want, such that the folder has the path content/topics/{topic-you-want}/stories/{firstname}-{lastname}-{#}.

This folder will contain your story itself and any dependencies that you want to reference (images, non-external links, etc.).

To create a folder via the Web UI, navigate to the stories folder under your desired topic and click "Add file." Prefix your file with your folder name. Since you'll eventually need the file, add your story.md file so that it's structured like {firstname}-{lastname}-{#}/story.md.

2. Add story metadata

Create an story.md file in your folder.

You can use the below template as a starting point:

---
title: Building out a Story
author: Geoffrey Xue
date: 2023-09-26
links:
  project: https://github.com/DSSD-Madison/Nagoya
---
This is an example story. Hello World!

The information in between the three dashes (---) is front matter, which is just metadata for the file. You'll want to configure these so you're credited correctly for your story and that it's searchable for future use!

• Adjust the title, author, and date of the file.

3. Edit story content

The story content can be written in both Markdown and HTML, but the HTML will require something called a shortcode. You can see examples of Markdown components and HTML embeds + custom HTML in the example story in the Github project and on the website.

4. Review and revise

Commit your changes and push a new branch to the project. Create a pull request to the project.

Under the comments, you should see an attached bot that provides a deploy preview to see a site with your story contributed! This can help to verify that there aren't any errors and also allow you to adjust the formatting of your story if something is out of place.

If you're looking for more customization, look into getting Hugo running locally from the README.md so you can instantly reload your changes.

5. Add a reviewer and update your pull request!

On the right side of your pull request, tag one of the contributors for review; we'll do our best to respond quickly and note if there's anything to change!