This repository builds and publishes an index of every repository in the Demo-Math-Journal organization. This file explains how it works and how to set it up. Do not edit README.md or data/repos.json directly — a workflow overwrites both on every run. index.html, assets/, site.json, and data/issues.json are hand-maintained and safe to edit.
- A GitHub Actions workflow runs
scripts/build-index.mjson a schedule. - The script calls the GitHub API to list every repository in the Demo-Math-Journal organization, except this one.
- For each repository, the script reads the top-level README and pulls out its first paragraph. If a repository has no README, the script falls back to the repository's short description on GitHub. If neither exists, the entry shows "No description available."
- For each repository, the script reads the contributor list and removes
bot accounts and
twoodwardMIDD. - The script writes two files:
data/repos.json(the data the website reads) andREADME.md(the same index, as shown on GitHub). If either changed, the workflow commits and pushes the update. index.htmlis a static page. When someone visits it,assets/index.jsfetchesdata/repos.jsonand renders the repo cards, filter, and math in the browser. Visitors never call the GitHub API, so there are no rate limits to worry about.
Edit index.html, assets/index.js (card layout and filtering),
assets/pdf-reader.js (PDF pane), or assets/style.css directly and
push. Changes go live as soon as GitHub Pages redeploys — no rebuild
needed. To change the site title or description, edit site.json; it is
copied into data/repos.json on the next build. (The fallback title in
index.html is only shown if JavaScript is off.)
data/repos.json is also a stable endpoint other pages can use:
https://demo-math-journal.github.io/data/repos.json.
Do these steps once, after you push this repository to
github.com/Demo-Math-Journal/Demo-Math-Journal.github.io.
Give this one repository its own write access with a scoped token, rather than changing the organization's default workflow permissions. The organization's default (read-only) is a reasonable one to leave in place for every other repo — this token grants write access to nothing but this repository.
- Create a fine-grained personal access token scoped to only the
Demo-Math-Journal.github.iorepository, with Contents: Read and write permission. (Settings > Developer settings > Personal access tokens > Fine-grained tokens.) - In this repository, open Settings > Secrets and variables > Actions.
- Select New repository secret. Name it
INDEX_REPO_TOKENand paste the token as the value. The workflow already looks for a secret with this exact name and uses it automatically — no other configuration change is needed. - Open Settings > Pages.
- Under Build and deployment > Source, select Deploy from a branch.
- Under Branch, select
mainand/ (root). Select Save. - Open the Actions tab.
- Select Build organization repository index in the left sidebar.
- Select Run workflow to trigger the first build by hand. Do not wait for the nightly schedule.
- After the run finishes, open
https://demo-math-journal.github.io/to see the published page.
Reading the other repositories' READMEs and contributors doesn't need
INDEX_REPO_TOKEN — the workflow uses the default GITHUB_TOKEN for that,
which always has read access to public repository data regardless of the
organization's workflow permissions policy. INDEX_REPO_TOKEN is only
used for the final push back to this repository.
If you'd rather have every repository in the organization default to read
and write access (broader than this task needs, but simpler if you expect
other repos to need it too), an organization owner can change it at
github.com/organizations/Demo-Math-Journal/settings/actions, under
Workflow permissions. With that changed, INDEX_REPO_TOKEN becomes
unnecessary — the workflow falls back to the default GITHUB_TOKEN
automatically if the secret isn't set.
Edit the cron line in .github/workflows/build-index.yml. The schedule
is in UTC. For example, '0 12 * * *' runs once at 12:00 UTC every day.
You can always trigger a build by hand from the Actions tab regardless of
the schedule.
The page groups repositories using their GitHub topics:
- A topic starting with
issue-puts the repository under that issue (issue-3→ "Issue 3"). Issues are listed newest first, compared numerically, soissue-10comes beforeissue-9. - Within an issue, a topic starting with
section-puts the repository under that section (section-root-finding→ "Root Finding"). Sections are listed alphabetically. - A repository with no
issue-topic is listed under "Other repositories" at the bottom; one with nosection-topic is listed under "Other" within its issue. An issue with no sections at all shows its repositories directly, without section headings. - If a repository has more than one
issue-(orsection-) topic, only the first in alphabetical order is used.
Topics are read during the nightly build, so a topic change shows up after the next run (or a manual run of the workflow).
Each issue's image and description, and each section's color, are set in
data/issues.json. See "Organizing issues and sections" in README.md for
the format.
- README parsing is heuristic, not a full Markdown parser. The script
skips headings, horizontal rules, tables, and badge-only lines (like
shields.io build badges), then takes the next paragraph. Unusual README
layouts — for example, a paragraph that starts with an inline image, or
heavy custom HTML — may need a tweak to
extractFirstParagraph()inscripts/build-index.mjs. - Contributors come from commit history, via GitHub's contributors API. This lists people who have committed code, not people who merely have repository access. A handful of repositories with unusually large contributor counts may show "too many to list" — GitHub's API declines to compute the full list for those.
- All repositories are included, including forks and archived repositories, with no filtering by topic or visibility.
- This assumes every repository in the organization is public. If any
repository is private, the default
GITHUB_TOKENwon't be able to read it, and the build log will show a warning for that repository (its README and contributors will be skipped, but it still appears in the index by name). To include private repositories, create a fine-grained personal access token with read access to the organization's repositories, add it as a repository secret (for example,ORG_READ_TOKEN), and change theGITHUB_TOKENenvironment variable inbuild-index.ymlto reference that secret instead ofsecrets.GITHUB_TOKEN.
GITHUB_TOKEN=<a token with public repo read access> \
GITHUB_ORG=Demo-Math-Journal \
node scripts/build-index.mjs
This writes README.md and data/repos.json in place. To preview the page,
serve the folder over HTTP (opening index.html as a file won't work,
because browsers block fetch() from file:// pages):
python3 -m http.server 8000
then open http://localhost:8000/.