Getting started

A publishing toolkit for technical work: readable articles, interactive figures, and a site you own.

Start with your project

Use the starter for a complete Astro site, or bring individual components into one you already maintain. Both use the same packages.

Create a new site

Start with working navigation, content sections, search, and publishing defaults. Your content and configuration stay in your project.

Create a site

npm create alkemist@canary -- my-lab --provider cloudflare
cd my-lab
npm install
npm run verify
npm run dev

Use --provider gitlab or --provider custom for another host. Open the local address printed by Astro.

Add to an existing site

Use a chart, a model viewer, or a navigation tree without replacing your site's layout. Each component has its own import.

Install components

npm install --save-exact @alkemdotdev/alkemist-components@canary

Try the component examples →

Working with a coding agent or source checkout

Give your agent a site name, destination directory, and preferred host. The complete agent setup instructions cover generation, customization, and deployment.

To use a reviewed source checkout instead of npm, generate into an empty directory:

Source generator

git clone https://github.com/alkemdotdev/alkemist.git alkemist-source
cd alkemist-source
npm ci
npm run create:site -- ../my-lab --provider cloudflare
cd ../my-lab
npm install
npm run verify
npm run dev

Use --provider gitlab or --provider custom for another host. The source generator keeps package snapshots in vendor/; commit those files with your lockfile.

To refresh those snapshots from a reviewed newer checkout, run npm run create:site -- ../my-lab --update, then install and verify in your site. This preserves site-owned content and configuration. npm-created sites instead use ordinary dependency upgrades; the npm generator has no update mode.

The canary channel tracks tested revisions of main. Keep the exact installed version in your lockfile and review upgrades before deploying.

Make it yours

Start with only the sections your readers need. A blog and an info page may be enough; add reference docs, a curated book, or interactive labs when you have content for them. Set your navigation, then adjust colors, typography, and image presentation.

Configure your site →

Publish your work

Build and inspect the site locally, including interactive figures and search. Then deploy the generated files using your host's Git integration or CI. Alkemist supports Cloudflare Pages, GitLab Pages, and other static hosts.

Build, verify, and deploy →