score-spec / score-spec/docs

Move `/docs/examples` under the new Examples Hub structure and associated process as `/examples/use-cases`

Open
#198 1 comment 0 reactions 1 assignee View on GitHub

@mathieu-benoit is already working on this.

Since Jul 4, 2025.

documentation enhancement
Dominant language
HTML
Stars
7
Forks
25
Avg merge
4d 5h
Merged PRs (30d)
3

Description

Is your feature request related to a problem? Please describe.

The current use case examples are great and useful to have in the Score docs, and I believe we should have more of those. However, authors will have to get acquainted, to some degree, with the Hugo website generator to add or modify content. This may defer people from contributing.

Describe the solution you'd like

Make it easier to contribute use case examples by placing the content in a separate GitHub repository that uses a simple, standard file and folder structure. Source content from there and generate the Hugo pages out of it using an automated workflow. A similar implementation is already in place for the Score example hub and could be expanded to cover the use cases.

Additional context

Acceptance criteria for the proposed solution:

  • A public GitHub repo defines a standard file and folder structure for maintaining use case examples
  • The structure is described in the README or CONTRIBUTING file of that repo
  • The example structure defines a single README for page content
  • The example structure allows the placement of one or more Score files
  • The example structure allows the placement of one more additional code files of any format
  • An automated GitHub workflow periodically pulls the current example content and generates one Hugo page underneath the Examples page for each example
  • All Score and code files are rendered into the page as code blocks
  • (nice to have) If more than one Score file is present, they are rendered into a collapsible section on the page
  • (nice to have) Same for the code files
  • All current use case example pages have been converted to the new approach, i.e. they are being sourced from the repo and auto-generated

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.