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
  ├─ @alkemist/astro  → shared integration and defaults
  └─ @alkemist/ui     → layouts, figure shells, theme tokens

The site consumes the actual workspace packages. This is the initial reusable boundary; published npm releases, migration commands, and a standalone starter test are still to come.

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

AlkLayout 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 AlkLayout from '@alkemist/ui/AlkLayout.astro';
---

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

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

Routine releases will update dependencies. Breaking changes require release notes and migrations that show their changes before applying them. The publishing contract includes a tested Astro peer range and checks against a separately installed consumer.