Site structure and navigation

The Alkemist demo uses Blog · Labs · Docs · Info · More. Docs leads directly to the component and setup references; More contains Test. The reusable layout defaults to Blog, Labs, and Info so sites without documentation need no extra configuration. On small screens, one hamburger menu contains both groups and keeps the header on a single row. These menus support keyboard activation, Escape to close and return focus, and dismissal by clicking outside. Navigation remains usable without JavaScript.

The appearance icon opens Whiteboard, Blackboard, and System choices. Sun, moon, and monitor icons show the selected preference. The preference is restored before paint and follows operating-system changes when System is selected. Arrow keys move through the choices; selecting with a pointer closes the panel.

Client-side widgets can share the same preference without depending on header markup:

import { getTheme, setTheme } from '@alkemist/ui/theme';

setTheme('dark'); // 'light', 'dark', or 'system'
const preference = getTheme();
window.addEventListener('alk:theme-change', () => {
  // Redraw a visualization using the current theme tokens.
});

These helpers run in the browser. AlkLayout initializes them; setTheme persists the preference when browser storage is available.

What belongs where

A lab is something to use. Its component reference lives in Docs. An article about how it was built belongs in Blog. Team biographies can use nested paths such as /info/team/person-name/; create those pages when you have real content for them.

Use lowercase kebab-case paths and trailing slashes for pages. Files retain extensions, and section anchors let one test page cover many specimens. Keep dates out of blog URLs and keep preview paths identical to production paths.

Your site owns its documentation

The theme does not inject Alkemist’s documentation into your site. Omit Docs entirely, or put your project’s own documentation there. The demo’s reference pages live in its content collection and consume the same reusable packages as the rest of the site.

AlkLayout accepts these optional arrays of { label, href } links:

For example, a site with project documentation can add it explicitly:

---
import AlkLayout from '@alkemist/ui/AlkLayout.astro';
---

<AlkLayout
  title="Our research group"
  navigation={[
    { label: 'Blog', href: '/blog/' },
    { label: 'Labs', href: '/labs/' },
    { label: 'Docs', href: '/docs/' },
    { label: 'Info', href: '/info/' },
  ]}
  moreNavigation={[{ label: 'Test', href: '/test/' }]}
>
  <slot />
</AlkLayout>

The demo’s src/layouts/SiteLayout.astro supplies its main, More, and footer links. A site without documentation can use AlkLayout directly. Supplying navigation replaces the default main links, so unused sections need not appear either.

Current files

src/
  content/
    blog/*.mdx
    docs/*.mdx
  layouts/SiteLayout.astro
  pages/
    blog/           # collection index and article route
    labs/           # actual Astro applications
    info/           # site-owned information pages
    docs/           # collection routes and component catalog
    test.astro      # one comprehensive test page
public/             # public downloads and other unprocessed assets

The blog and docs currently require title and description; order defaults to 100 and date is optional. Blog entries sort by date descending, then order and ID. They remain MDX collections with file-derived IDs.

Explicit stable IDs, separate route slugs, .md support, portable article folders, source-relative asset resolution, *.alk.yaml sidecars, and *.figure.yaml definitions are proposed next steps. Those file contracts are not implemented by this route change. Current charts and models still take explicit public asset URLs and their documented component props.

Existing links

Published notebook pages redirect permanently to Blog, /components/ redirects to /docs/components/, and the old design-study URLs redirect to their corresponding Labs pages. Published downloads retain their old URLs, including the image at /notebook/eight-inks.jpg.

apps/site/redirects.mjs is the source for both Astro’s static redirect pages and Cloudflare’s generated _redirects rules. Cloudflare applies the HTTP redirects at deployment; Astro’s static output supplies fallback redirect pages for other static hosts. See the Cloudflare redirect documentation for hosting behavior.