NUSV.github.io

The official website of United Science Vaca (NUSV), built as a static site and served from GitHub Pages at nusv.github.io.

How the site stays fresh

A GitHub Actions workflow (.github/workflows/sync.yml) runs tools/sync_data.py every 6 hours (and on manual dispatch) to:

1. list every repository in the NUSV organization,
2. pick the ones tagged with the topic nusv-project,
3. regenerate each project page under projects/ (README introduction, latest releases, downloads, auto-discovered icon, optional screenshots),
4. refresh the listings on index.html (featured grid) and warehouse.html — only the marker regions <!-- …-GRID:start/end --> are rewritten; hand-written copy is preserved.

Only changes are committed; an unchanged run pushes nothing.

Adding a new project (no website edits needed)

1. Create a repository in the NUSV organization (or transfer an existing one), public.
2. Tag it with the project topic:

   gh repo edit NUSV/your-repo --add-topic nusv-project

3. Optional, for a nicer listing — add site.json in the repo root:

   {
     "slug": "friendly-page-url",
     "name": "Display Name",
     "tagline": "One-line description for cards and the page header.",
     "platforms": ["Android", "Windows"],
     "docs": "/docs/your-repo.html",
     "icon": "path/inside/repo.png"
   }

   Without site.json the generator falls back to the repository description, the repository name (minus a trailing -NUSV), and no platform chips.
4. The page icon is auto-discovered: any *.png in the repo root named like the repo or starting with logo/icon (the last one alphabetically wins). To add a screenshot gallery, put images under screenshots/, docs/screenshots/ or assets/screenshots/.

That's it. The next scheduled sync (or a manual Run workflow on the Sync project data action) adds the project page and listing cards. To trigger a sync instantly from a release pipeline:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/NUSV/NUSV.github.io/dispatches \
  -d '{"event_type":"sync-projects"}'

Removing the topic removes the project from the website on the next sync. Infrastructure repositories (.github, NUSV.github.io, nusv-lite-sync, forks) never carry the topic, so they stay off the listings automatically.

Mirrored documents

Besides release binaries, the important documents of every project are mirrored as site pages too, so they stay readable where GitHub is slow or blocked:

• Root-level *.md files (except README.md, which is already the project page) and everything under docs/**/*.md are rendered to /mirror/<project>/<doc>.html with the site's own styling, plus a link to the original on GitHub. (The /docs/ section stays reserved for the hand-written technical documentation.)
• Links inside rendered READMEs to mirrored documents are rewritten to the local pages.
• Images referenced by mirrored content are downloaded to assets/mirror/<repo>/… and served from the site (only the header icons today, but the pipeline handles any image).
• docs.html gains a generated "Mirrored documents" index; project pages gain a "Documents" sidebar card.

Download mirror (no VPN needed)

GitHub release downloads are slow or blocked in some regions. The sibling repository NUSV/downloads mirrors the latest release assets of every project and serves them via GitHub Pages:

• https://nusv.github.io/downloads/ — human-readable listing
• https://nusv.github.io/downloads/downloads.json — machine-readable manifest

The mirror refreshes every 6 hours (orphan-commit + force-push keeps its history at one snapshot). tools/sync_data.py reads the manifest and points project-page download buttons at the mirror whenever it matches the current latest release; otherwise buttons fall back to GitHub. Assets that are missing from the mirror always remain available on each project's GitHub Releases page.

Pages

File	Purpose
index.html	Home — hero, stats; the featured grid is generated
warehouse.html	Warehouse — generated project cards + hand-written intro
docs.html	Hand-written technical-docs hub
docs/syna.html, docs/nusv-lite.html, docs/gomoku.html	Hand-written deep technical docs (architecture, protocol, builds)
projects/<slug>.html	Generated per-project pages (intro + downloads)
about.html, 404.html	Static pages
tools/sync_data.py	The generator (pure Python 3 stdlib, no dependencies)

Editing

No build step for the hand-written pages: edit the HTML directly; styling lives in assets/css/style.css, scripts in assets/js/main.js, brand assets in assets/img/. Push to main — GitHub Pages deploys automatically.

Languages (i18n)

English is the source language and is served inline. A Chinese translation ships in assets/js/i18n.js; the EN / 中文 toggle in the navigation applies it client-side and remembers the choice via localStorage.

• Mark an element with data-i18n="key" — the dictionary value replaces its inner HTML.
• Placeholders {n} / {name} / {doc} are filled from data-i18n-args.
• data-i18n-title (plus args) on the <html> tag translates document.title.
• Generated pages (project pages, mirrored documents, listing grids) emit the same attributes from tools/sync_data.py, so new projects get the toggle for free.
• Mirrored repository documents and the hand-written technical docs stay in their original language; translated documents (e.g. Syna's Chinese tutorial) are mirrored as separate pages.

To add another language: add a dictionary under window.I18N in assets/js/i18n.js and extend the toggle cycle in assets/js/main.js.

English is served inline so the site remains fully readable without JavaScript.

License

MIT — see the NUSV organization for details.