Adding resources to the website

[chartgerink]

We often share resources in the Slack channel, which are of value to the many people involved in this project. Such resources are primarily links, potentially with some extra context to help understand why it might be relevant. Those resources depend on participation at a specific time in the Slack, and easily get lost over time. They could very well have a lifetime beyond that!

In this topic, I propose a way for us to collectively share resources and make them available beyond the Slack channel with minimal effort. This is the result of a need that was indicated by several people to have a resources page on the website, instead of just on different slack channels people may or may not be in.

cc @Bisaloo

Submitting resources

I propose to use a special category in the GitHub discussion forum called "Resources" (or such), where resources are shared. This way we would not need additional infrastructures to post and the biggest barrier is using GitHub for this.

To post in the "Resources" category, people will fill out a GitHub discussion form that asks for:

• Title
• URL
• Context
• Labels

Such a form allows us to structure the content and preselect labels for the resources (preventing wildgrowth on this). The resources are immediately available as a GitHub discussion with all the features that gives (upvoting, threading). An initial proposal is included below for this form.

Open for form syntax

This would live under .github/DISCUSSION_TEMPLATE/resources.yml for example.

title: "<replace with resource title>"
body:
  - type: markdown
    attributes:
      value: "## Resource Submission\nPlease provide the following details about the resource you are sharing."

  - type: input
    id: url
    attributes:
      label: 'URL'
      description: 'Provide the direct URL to the resource.'
      placeholder: 'https://example.com'
    validations:
      required: true

  - type: textarea
    id: context
    attributes:
      label: 'Context'
      description: 'Provide any additional context about the resource. Why is it useful? Who might it benefit?'
      placeholder: 'This guide is useful for those looking to understand React from scratch.'
    validations:
      required: true

  - type: checkboxes
    id: labels
    attributes:
      label: 'Labels'
      description: 'Select appropriate labels for this resource (you can select multiple).'
      options:
        - label: 'documentation'
        - label: 'tools'
        - label: 'best-practices'
        - label: 'tutorial'
    validations:
      required: true

We could optionally create a workflow to actually mark the discussions on the GitHub side with the same labels as well.

Processing submitted resources

We can use the discussions event in GitHub Actions, to run a workflow when a discussion is created. This way, we could add the resource to the website.

This new workflow would roughly work as follows:

• Activate workflow on new discussion created
• Only proceed if it is in the "Resources" category (no native GitHub Action filtering)
• Create a resource file with the relevant information under a dedicated folder (e.g., /resources/*.qmd)
• Commit the changes and (1) create a PR for review or (2) commit to main
• All the files under /resources/* will get rendered in a Quarto listing page

Open for workflow idea

name: Create QMD File on New Discussion in 'Resources'

on:
  discussion:
    types: [created]

jobs:
  createQMD:
    runs-on: ubuntu-latest
    if: github.event.discussion.category.name == 'Resources'
    steps:
    - name: Checkout repository
      uses: actions/checkout@v3

    - name: Generate QMD file
      uses: actions/github-script@v5
      with:
        script: |
          const fs = require('fs');
          const discussion = context.payload.discussion;
          const fileName = `resources/${discussion.id}.qmd`;

          const qmdContent = `---
title: "${discussion.title.replace(/"/g, '""')}"
author: "${discussion.user.login}"
date: "${new Date(discussion.created_at).toISOString()}"
category: "${discussion.category.name}"
labels: [${discussion.labels.map(label => `"${label.name}"`).join(', ')}]
discussion_url: "${discussion.html_url}"
context: "${discussion.body}"
---
`;

          fs.writeFileSync(fileName, qmdContent);

    - name: Commit and push changes
      uses: EndBug/add-and-commit@v9
      with:
        author_name: Epiverse Bot
        author_email: epiverse@data.org
        message: 'Add discussion: ${{ github.event.discussion.title }}'
        add: 'resources/*.qmd'

Remaining questions

• Would we want to be able to sort the resources based on the amount of upvotes on GitHub as well? As in, if an old resource has a lot of upvotes, it may help to make that more easily findable that way.
  • We could do this by adding: (1) another workflow that checks and updates that count in the YAML metadata for each discussion and (2) we create a custom list sort based on that metadata - but note this is not a default action and requires a bit of finagling (see details below).

In the yaml for the listing page:

sort-ui:
    - title
    - date
    - upvotes
  template: custom_listing.ejs
  field-types:
    date: date
    upvotes: number

With the custom_listing.ejs being

```{=html}
<div class="archive list">
    <% for (const item of items) { %>

    <div class="quarto-post image-right" <%= metadataAttrs(item) %>>
        <% if (item.image) { %>
        <div class="thumbnail">
            <a href="<%- item.path %>" class="no-external"></a></p><a
                href="<%- item.path %>" class="no-external">
                <p><img src="<%- item.image %>" class="thumbnail-image"></p>
            </a>
        </div>
        <% } %>
        <div class="body">
            <h3 class="no-anchor listing-title"><a href="<%- item.path %>" class="no-external"><%= item.title %></a></h3>
            <div class="listing-subtitle"><a href="<%- item.path %>" class="no-external"><%= item.subtitle %></a></div>
            <span class="ratings">
                <span class="rating listing-upvotes rating-upvotes-<%= item.upvotes %> "></span>
            </span>
            <% if (item.categories) { %>
            <div class="listing-categories">
                <% for (const category of item.categories) { %>
            <div class="listing-category" onclick="window.quartoListingCategory('<%=category%>'); return false;"><%= category %></div>
                <% } %>
            </div>
            <% } %>
        </div>
        <div class="metadata"><a href="<%- item.path %>" class="no-external">
            <span class="archive-item-date">
                <span class="listing-date">
                    <%= item.date %>
                </span>
            </span>
        </div>
    </div>
    <% } %>
</div>

[Bisaloo]

Thanks for starting this discussion!

A couple of questions or design decisions to make:

• How to deal with duplicates?
• Should there be a threshold of upvotes for a resource to be added to prevent information overflow and ensure only the resources the community finds most useful are displayed?
• Can there be a system to add new tags/keywords to an existing resource?

[chartgerink]

Good questions 😊

1. I would propose to (1) add a disclaimer to the form that duplicate resources may be removed and (2) moderate the forum for this. This would need an additional workflow trigger when a discussion is deleted.
2. I would propose to defer this to the moment that a need for this arises - we could preempt this need by implementing a threshold of 1 and upgrade the threshold if this need is identified later on.
3. That sounds desirable - we might be able to use the labeled event for GH Discussions to update the labels accordingly in the resources/*.qmd file. I would suggest to include this only in the first iteration after an MVP personally, to limit the scope for now.

[chartgerink]

Form for submitting resources is proposed and open for discussion: #234