Site structure and navigation

Alkemist offers six publishing conventions: Blog · Logs · Labs · Slides · Docs · Book. Info remains the place for project background. Use only the sections that help your readers; these names and divisions are starting points, not a required taxonomy.

The demo shows all six so you can try each format. Adopting projects own their navigation and content. On small screens, the header puts navigation in one keyboard-accessible menu; More holds the Test page.

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 '@alkemdotdev/alkemist-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. Layout initializes them; setTheme persists the preference when browser storage is available.

What belongs where

Docs and Book serve different reading needs. Docs explains a component’s properties or a configuration option. Book leads a reader through a complete task and links to those references when needed. A project may need either, both, or neither.

A short log can eventually inspire an article. A lab can have a related article and a reference page. Link those pieces; there is no requirement to duplicate content or assign everything a universal type. Existing blog addresses remain unchanged.

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.

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

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

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

<Layout
  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 />
</Layout>

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

Configure an adopting project

In the source starter, edit src/lib/site.ts:

export const sections = {
  blog: { enabled: true, label: 'Articles' },
  logs: { enabled: true, label: 'Notes' },
  labs: { enabled: true, label: 'Labs' },
  slides: { enabled: true, label: 'Slides' },
  docs: { enabled: false, label: 'Docs' },
  book: { enabled: false, label: 'Book' },
  info: { enabled: true, label: 'Info' },
} as const;

The object order determines navigation order. Changing a label changes its display name, while /blog/ and /logs/ remain stable. Set enabled: false to omit a section’s navigation and routes. Keep your content sources, then enable the section when it is ready. Site links include the deployment base, including GitLab project paths.

The starting examples demonstrate all six formats. They are editable content in your application, not content injected by the integration. Add custom Astro routes and navigation when your project needs a different shape.

Authoring the formats

Blog and Logs are chronological collections. Give an entry a title, description, and date; keep a log small enough to scan in its feed. Draft entries stay out of public feeds and detail routes. Slides contains Markdown or MDX decks with format: slides; see the browser slides guide. The Book collection uses explicit chapter order rather than publication dates, with a contents page and previous/next links. Docs remains reference material organized around the project. Labs contains Astro pages with the actual interactive applications.

The source starter supplies examples and owns the route generation. Disabling a starter section omits its index and detail pages from the build and removes its navigation links; content files remain available for later use. Its verification script checks the generated links. Adding arbitrary new sections or changing route names is a normal site-owned Astro change, not a promise that labels rewrite URLs.

The demo’s src/lib/sections.ts configures navigation labels and visibility. Its established Blog, Docs, and Labs routes remain published to preserve existing links; hiding those navigation entries does not delete their routes. The starter’s optional route generation is intended for new adopting projects.

These scaffold additions are available in the source starter. The already published [email protected] keeps its original files until the next deliberate package release. Generated sites are user-owned: neither updating dependencies nor running the generator again silently changes their content structure.

Post images

Blog entries can declare an optional cover image once for both their listing thumbnail and article header. The thumbnail uses a consistent frame with configurable fit and focal point; the article preserves natural image proportions. See blog thumbnails and covers for frontmatter fields and examples.

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.