Create a "good first issue" page

We need to add a page that shows GitHub issues labeled with "good first issue" to advise people on how they can start to work on open-source software (OSS).

Technical steps to add such a page

Step 1: Create the Node.js Script

Save the following script as fetch_issues.js in the root directory:

const fetch = require('node-fetch');
const fs = require('fs');

const GITHUB_TOKEN = 'YOUR_GITHUB_TOKEN_HERE';  // Optional, but recommended
const REPOS = [
    'owner/repo1',
    'owner/repo2',
    'owner/repo3'
    // Add more repositories here
];

const HEADERS = {
    'Accept': 'application/vnd.github.v3+json',
    'Authorization': `token ${GITHUB_TOKEN}`  // If you don't have a token, remove this line
};

async function fetchGoodFirstIssues(repo) {
    const url = `https://api.github.com/repos/${repo}/issues?labels=good%20first%20issue&state=open`;

    try {
        const response = await fetch(url, { headers: HEADERS });
        if (!response.ok) {
            throw new Error(`Error fetching data from ${repo}: ${response.statusText}`);
        }

        const issues = await response.json();
        return issues.map(issue => ({
            title: issue.title,
            url: issue.html_url,
            created_at: issue.created_at,
            repo: repo
        }));
    } catch (error) {
        console.error(`Error fetching from ${repo}:`, error);
        return [];
    }
}

async function main() {
    const allIssues = [];
    for (const repo of REPOS) {
        const issues = await fetchGoodFirstIssues(repo);
        allIssues.push(...issues);
    }
    fs.writeFileSync('./data/issues.json', JSON.stringify(allIssues, null, 2));
    console.log('Issues successfully saved!');
}

main();

Step 2: Adjust the Hugo Build Process

Add a new script in your package.json that runs the Node.js script before Hugo generates the pages:

{
  "scripts": {
    "fetch-issues": "node fetch_issues.js",
    "build": "npm run fetch-issues && hugo"
  }
}

This ensures that the Node.js script runs every time you execute npm run build. The script generates an issues.json file in your Hugo project’s data directory.

Step 3: Create a Hugo Shortcode

Create a shortcode that reads the JSON data and converts it into HTML. Create a file layouts/shortcodes/issues.html with the following content:

{{ $issues := .Site.Data.issues }}
<ul>
    {{ range $issues }}
    <li>
        <a href="{{ .url }}">{{ .title }}</a> - {{ .repo }}
        <br>
        <small>Created on: {{ .created_at }}</small>
    </li>
    {{ end }}
</ul>

Step 4: Use the Shortcode in a Page

Now, you can use the shortcode in any Hugo page:

---
title: "Good First Issues"
date: 2024-08-27
---

Here are some "Good First Issues" from the specified GitHub repositories:

{{< issues >}}

Design of the page

A design for the page will be added to this issue.

For each issue we want to have the following information:

Title of the issue
Link to the issue on GitHub
Information about issue type (Java, HTML, Hugo, ....) best as small but colorfull logos.

OpenElements / open-elements-website