Contributing

All Reuters Graphics staff are welcome and encouraged to add to and improve this guide. All contributions must be made in the GitHub repo for this project.

Structure of the Project

This site is built using Starlight and the Astro web framework. But in most cases, you’ll only need to know a bit of basic markdown syntax to contribute documentation.

All documentation files are stored as .mdx files in the src/content/docs directory. Each MDX file creates a corresponding page on this site. Nested pages create more complex URLs.

• Directorysrc

  • Directorycontent

    • Directorydocs

      • index.mdx Home page
      • Directorytutorials

        • my-tutorial.mdx A page at /tutorials/my-tutorial/

Updating existing pages

If you’re editing typos, updating links or adding simple instructions to an existing page, you can make those changes directly in GitHub and commit to main.

For more substantial edits, follow a normal GitHub flow:

1. Create a new branch: Clone this repo, if you haven’t already, and create a new branch.

   git checkout -b your-branch-name

2. Edit the MDX file:

   • Navigate to the src/content/docs/ directory.
   • Open the file for the page you want to edit and make your changes.

3. Commit your changes: After making changes, commit them with a meaningful message and push your branch to GitHub.

   git add .
   git commit -m "My docs edit"
   git push origin your-branch-name

4. Open a Pull Request (PR):

   • Go to GitHub and open a PR from your branch to the main branch.
   • Add a clear description of your changes for review.

Adding new pages

1. Create a new branch:

   git checkout -b your-branch-name

2. Add a new MDX file:

   • Navigate to the src/content/docs/ directory.
   • Create a new .mdx file for your page.
     • For example, if you want to add a new page about creating choropleth maps, you might create a file called choropleth-maps.mdx.
   • Start the file with a YAML frontmatter section that includes at least a title field:

     ---
     title: Choropleth Maps
     description: How to create choropleth maps using Datawrapper.
     ---

3. Write your content: Use Markdown and MDX features to structure your content. You can also use any of Starlight’s built-in MDX components:

   ---
   title: Choropleth Maps
   ---
   
   import { Aside } from '@astrojs/starlight/components';
   
   ## Upload Your Data
   
   Follow these steps to upload your dataset to Datawrapper...
   
   <Aside type="caution">Be sure your data is formatted properly!</Aside>

Images

When adding images to accompany your documentation, please save them near the MDX file they belong to, typically in an images/ subdirectory within the same folder as the MDX file you’re working on.

You can then import the image directly into your MDX file and place it in your content:

import MapImage from './images/choropleth-example.png';

## Example Choropleth Map

Here’s what a choropleth map looks like:

<img src={MapImage.src} />

Adding a page to the site nav

To add your new page to the sidebar nav, you must add an item to the SIDEBAR array in the astro.config.mjs file in the root of this project with a label and slug which represents the path to your page.

const SIDEBAR = [
  // ...
  {
    label: 'My new tutorial',
    slug: 'tutorials/my-new-tutorial',
  },
];

Starting the dev server

1. Install dependencies using pnpm:

   pnpm i

   Tip

   This repo uses pnpm, which is a package manager, like yarn or npm, but cooler. If you don’t have it, you can install it with npm:

   npm install -g pnpm

2. Run the dev server:

   pnpm dev

Publishing Changes

Once your PR is approved and merged or any changes have been made to the main branch, the site will automatically be republished through a GitHub Action.