Architecture and upgrades

A copied template is easy to start using, but upgrading it can become a merge between the template author’s edits and your own. Alkemist puts the maintained behavior in versioned packages and leaves your content, data, and identity in your application.

The package boundary

Your Astro site
  ├─ content, datasets, models, custom pages
  ├─ @alkemdotdev/alkemist-components → layouts, figures, charts, models, math, code, audio, and video
  ├─ @alkemdotdev/alkemist-theme      → optional tokens, CSS, and theme helpers
  └─ @alkemdotdev/alkemist-astro      → optional integration and MDX defaults

Use the source generator for a new site and its explicit --update snapshot refresh path. The published 1.0.0-beta.1 packages use the earlier interface; the next deliberate package release will publish this source interface.

Starlight is the architectural precedent: a maintained Astro integration with configuration and component overrides. Alkemist’s interface centers on scientific articles, notebooks, and experiments. Starlight overrides and Astro integration API.

Theme the shared components

Layout provides the shared page shell. Its public props are title, description, section, and preview; siteName, tagline, and faviconHref set your identity. It also accepts navigation, moreNavigation, and footerNavigation. Home, favicon, and default navigation links respect Astro’s configured base path. See site structure and navigation for the link arrays and how to omit Docs in a consuming site.

---
import Layout from '@alkemdotdev/alkemist-components/layout';
---

<Layout title="A research notebook" section="Experiments">
  <h1>Working notes</h1>
</Layout>

Theme tokens use the --alk- prefix. Whiteboard (#eee) and Blackboard (#111) share Ubuntu typography and the same eight ink values. Neutral foreground text follows the surface; annotations and graph marks keep their color. Fonts are served locally. Override tokens in your application’s stylesheet instead of editing package internals.

:root {
  --alk-accent: light-dark(#28577b, #a6c8ed);
}

Upgrade policy

Versions are fixed across @alkemdotdev/alkemist-components, @alkemdotdev/alkemist-theme, and @alkemdotdev/alkemist-astro. Changesets describe each release; prereleases publish with the beta tag, then a new stable version can publish to latest after leaving pre mode. The release workflow authenticates through GitHub OIDC, with no long-lived npm token in the repository or Cloudflare environment.

For a generated site, refresh only from a reviewed newer source checkout with npm run create:site -- ../my-lab --update, then reinstall, verify, review the diff, and exercise customized pages. The registry generator creates a project once and does not take ownership of its files afterward. See the publishing guide for the release controls and current registry boundary.