Skip to content

New documentation site: Astro + Starlight, indigo theme, new icon - #8

Merged
FarooqKhan merged 9 commits into
masterfrom
website-overhaul
Nov 15, 2026
Merged

FarooqKhan merged 9 commits into
masterfrom
website-overhaul

Conversation

@FarooqKhan

@FarooqKhan FarooqKhan commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Replaces the Jekyll site with an Astro + Starlight documentation site for jsondb-core 1.1.16. It adds the new indigo theme, a redesigned icon, a Build-and-deploy workflow, and Dependabot. Part of Jsondb/jsondb-core#80.

Design and plan: docs/superpowers/specs/2026-11-16-website-overhaul-design.md and docs/superpowers/plans/2026-11-16-website-overhaul.md.

Where to look

Review closely

  • src/content/docs/guides/*.md — technical accuracy against 1.1.16. Check most closely schema-versions.md (you must open with compatibilityMode = true), find-and-modify.md (the conversion table), crud.md (which operation fails when), and encryption.md (key handling advice).
  • .github/workflows/deploy.yml — build runs on every PR; deploy runs only on push to master, with pages: write / id-token: write scoped to that job.
  • astro.config.mjs — the sidebar, the head tags (favicons, og:image), and the edit-link base …/edit/master/.
  • src/content/docs/reference/upgrading.md and security.md — claims about 1.0.x → 1.1.x behaviour changes and how to report vulnerabilities.

Skim

  • src/content/docs/index.mdx, src/components/*.astro, src/styles/theme.css — the landing page and theme.
  • src/content/docs/start/*, reference/xpath-cheatsheet.md.
  • scripts/build-icons.mjs, src/assets/logo*.svg.
  • .github/dependabot.yml — npm and github-actions, weekly, each grouped into one PR.

Safe to skip

  • public/*.png, public/favicon.ico — generated by npm run icons.
  • package-lock.json.
  • docs/superpowers/* — the spec and plan; Astro ignores them.
  • All the deleted Jekyll files (_posts/, _includes/, Gemfile*, img/, …).

How it was checked

  • Every code sample was run against io.jsondb:jsondb-core:1.1.16 from Maven Central, in a scratch project (not committed) compiled with --release 8: 112 assertions, all passing. Each one checks a claim the docs make, including every query in the cheat sheet, every slice in the slicing table, every row of the conversion table, and the backup path rules. This caught several things the docs now state correctly:
    • in 1.1.16 a misspelt collection name on insert/save/upsert/remove throws a bare NullPointerException;
    • an old-schema file doesn't load at all unless compatibilityMode is on;
    • re-adding a listener after removing the last one doesn't restart the watcher.
  • A clean npm ci && npm run build passes, and starlight-links-validator reports all internal links valid, anchors included.
  • Every external link returns 200.
  • npm audit: 0 vulnerabilities. The 63 Dependabot alerts GitHub reports on master all come from the old Gemfile.lock, which this PR deletes.
  • The icons were rendered and inspected at 16, 32 and 180 px, plus the 1200×630 social card.
  • Not yet checked in a browser by a person. Please look at the landing page, a guide, search, light and dark mode, phone width, and the tab favicon before merging.

What this does not do

  • The Pages source isn't part of this PR. It has already been switched to "GitHub Actions", separately from this PR, so the merge deploys the new site. The old build keeps serving until then.
  • LICENSE.txt is deleted, with nothing replacing it. It was the MIT licence of the old theme (© 2014 Tim O'Brien), which this PR removes.
  • It doesn't document unreleased jsondb-core changes such as setSyncFolderOnWrite. A few pages warn about 1.1.16 behaviour that's fixed on master; update them when the next release ships.
  • It doesn't add analytics. The dead Universal Analytics tag is gone, with nothing replacing it, as agreed.
  • Branch protection isn't part of this PR. It's already applied to master: the build check is required, it needs 1 approval with a FarooqKhan bypass, and admins are included.

@FarooqKhan
FarooqKhan merged commit fd23342 into master Nov 15, 2026
2 checks passed
@FarooqKhan
FarooqKhan deleted the website-overhaul branch November 15, 2026 23:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant