How bytes.io works

1. The index

Every known library is listed in index.json, kept in Bytes-Repository/repository. It's an array of single-key objects mapping a library name to its GitHub URL:

[
  { "mold": "https://github.com/Bytes-Repository/mold" },
  { "obsidian": "https://github.com/Bytes-Repository/obsidian" },
  { "tui": "https://github.com/Bytes-Repository/tui" },
  { "silver": "https://github.com/Bytes-Repository/silver" },
  { "nidus": "https://github.com/Bytes-Repository/nidus" }
]

This whole site fetches that file directly from GitHub at load time, so adding a library is a single pull request — no publish step, no build.

2. The manifest — Bytes.hk

Each repo carries a Bytes.hk file at its root (some older repos still spell it bytes.hk — bytes.io checks both), playing the role Cargo.toml plays for Rust — with its own [section] / -> key => value syntax rather than braces:

[package]
-> name        => mold
-> version     => 0.4.2
-> author      => janekk
-> license     => MIT
-> description => Molding utilities for H#

[deps]
-> obsidian => ^1.2.0   ;; core IR types
-> silver   => >=0.3

[build]
-> lang   => h#
-> entry  => src/main.h#
-> output => build/mold
-> emit   => bin

[stats]
-> downloads => 15234
-> stars     => 342
-> tags      => [cli, parser, compression]

[downloads]
-> 0.4.2 => 8210
-> 0.4.1 => 4120
-> 0.4.0 => 2104
-> 0.3.0 => 800

Lines starting with ;; are comments and run to end of line — plain # is not a comment marker, since it shows up literally inside real values (the language is called "H#"). bytes.io fetches and parses this file client-side to render the package, dependency, build, and stats panels on each library's page. A single author entry works the same as an authors list. The [stats] section is optional — downloads and stars render as figures (falling back to the repo's live GitHub star/fork counts when this section is missing), and tags render as pills (falling back to GitHub topics). The optional [downloads] section breaks that total down per version, crates.io-style: each key is a version string, each value its download count, rendered as a bar chart sorted by version.

3. Language detection

The language bar on every library page starts from GitHub's own /languages API, then adds five extensions GitHub's linguist doesn't recognize by walking the repo's file tree:

When H# is a repo's dominant language, its page shows the glossy H# badge instead of a plain legend dot.

4. Search, filters & sorting

The search box on the homepage matches against a library's name, its [package] description, and its [stats] tags — not just the name. The language dropdown and tag chips underneath narrow the grid further, and the sort control reorders it by name, downloads, stars, or how recently Bytes.hk was last touched. All of this runs on data gathered in the background right after index.json loads: each library's language, description (falling back to the repo's GitHub description when the manifest is silent or missing), tags, and last-commit date get fetched a few at a time and cached, so cards fill in progressively instead of blocking the page.

5. Caching & offline support

index.json and every per-repo lookup (language bytes, manifest contents, commit dates, GitHub profiles) are cached in localStorage with a time-to-live — ten minutes for the index, six hours for repo metadata. Repeat visits render instantly from cache while a fresh copy loads quietly underneath, so the grid never sits on a blank skeleton once you've been here before.

On top of that, bytes.io registers a service worker that caches the app shell (HTML, CSS, JS, icons) so the site still opens with no connection, and it ships a web app manifest so it can be installed like a native app. If a page fails to load offline and isn't cached yet, you land on a dedicated offline page instead of a browser error.

6. Manifest history & author pages

Every library page has a "Manifest history" panel pulling the real commit log for Bytes.hk from GitHub's API — so you can see how a package's dependencies or version evolved over time, not just its current state. Downloads-by-version bars are sorted with a spec-correct SemVer 2.0.0 comparator, so pre-release versions like 1.0.0-beta.1 land in the right place instead of a naive dot-split sort mangling them.

Each name in @package.authors links to a profile page combining that person's public GitHub profile with every bytes.io library that lists them as an author. That lookup normally comes from a prebuilt reverse index (data/authors-index.json, generated by scripts/generate-site-data.mjs) instead of scanning every manifest live on each visit; if an author was added since the index was last built, the page falls back to a live scan automatically.

7. Badges

The badge generator builds shields.io-style status badges entirely in the browser: it measures the label/message text, draws an SVG, and encodes it as a data: URI. That means the markdown snippet you copy into a README is fully self-contained — no third-party image host, nothing that can go down or rate-limit you.

8. Recently added & the Atom feed

Because bytes.io has no backend, the recently added page tracks "first seen" dates for each library locally, in your browser — a good way to spot what's new to you. For a real, global publish timeline, feed.xml is generated server-side by scripts/generate-feed.mjs, a small script meant to run on a schedule (e.g. a daily GitHub Actions cron job) that diffs index.json against the previous feed to timestamp genuinely new entries.

9. Dark mode

The toggle in the top-right corner switches between light and dark themes and remembers your choice in localStorage. With no saved preference, the site follows your OS setting automatically. The switch is applied before the page paints, so there's no flash of the wrong theme on load.