@axerity/cli 0.1.0

package/src/content/demo/installation.md

@@ -0,0 +1,49 @@
+---
+title: Installation
+description: Get Axerity running locally in a minute.
+icon: download
+---
+
+# Installation
+
+Axerity is a CLI. You do not clone or fork anything. Install it, scaffold a site,
+and start writing Markdown.
+
+## Requirements
+
+- Node.js 20 or newer
+
+## Create a site
+
+Scaffold a new site with `init`, then start the dev server:
+
+```bash
+npx axerity init my-docs
+cd my-docs
+npx axerity dev
+```
+
+Your site is running at `http://localhost:5173`. Or install it globally and drop
+the `npx`:
+
+```bash
+npm install -g axerity
+axerity init my-docs
+```
+
+## Project layout
+
+A site is just your content and one config file. Everything else lives in the
+package:
+
+```
+my-docs/
+  axerity.json     site configuration
+  docs/            your markdown + meta.json
+  public/          optional images and assets
+```
+
+Write Markdown in `docs/`, order pages with `meta.json`, and configure the site
+in [`axerity.json`](/configuration). The CLI builds a hidden `.axerity`
+workspace to run the engine against your content, so add `.axerity` to your
+`.gitignore` (the scaffold does this for you).

package/src/content/demo/meta.json

@@ -0,0 +1,15 @@
+{
+	"title": "Getting Started",
+	"icon": "rocket",
+	"pages": [
+		"index",
+		"installation",
+		"quick-start",
+		"writing",
+		"configuration",
+		"theming",
+		"components",
+		"api",
+		"changelog"
+	]
+}

package/src/content/demo/quick-start.md

@@ -0,0 +1,47 @@
+---
+title: Quick Start
+description: Write your first page in two minutes.
+icon: rocket
+badge: New
+---
+
+# Quick Start
+
+Adding a page is just creating a Markdown file. Let's add one.
+
+## Create a page
+
+Make a new file at `src/content/docs/hello.md`:
+
+```md
+---
+title: Hello
+icon: book-open
+---
+
+# Hello
+
+My first Axerity page.
+```
+
+It's immediately available at `/hello` and shows up in the sidebar.
+
+## Order it with meta.json
+
+Each folder has a `meta.json` that controls titles, icons, and ordering:
+
+```json
+{
+	"title": "Getting Started",
+	"icon": "rocket",
+	"pages": ["index", "installation", "quick-start", "hello"]
+}
+```
+
+Pages listed in `pages` appear in that order; anything you leave out is appended
+alphabetically.
+
+## Organize with folders
+
+Create a subfolder with its own `meta.json` and it becomes a new sidebar
+section. Subfolders are ordered by naming them in the parent's `pages` list.

package/src/content/demo/theming/advanced.md

@@ -0,0 +1,116 @@
+---
+title: Advanced
+description: Radius, custom tokens, prose, and whole new themes.
+icon: sliders
+---
+
+<script>
+	import { Callout } from '$lib';
+</script>
+
+# Advanced theming
+
+Everything you need to take theming as far as you want.
+
+## Roundness
+
+Axerity overrides Tailwind's radius scale in one place, so **every** `rounded-*`
+utility across the UI changes at once:
+
+```css title="src/routes/layout.css"
+@theme inline {
+	--radius-sm: 0.125rem;
+	--radius-md: 0.25rem;
+	--radius-lg: 0.375rem;
+	--radius-xl: 0.5rem;
+	--radius-2xl: 0.625rem;
+}
+```
+
+Want pill-soft corners? Scale these up. Want sharp, terminal-like edges? Set them
+all to `0`.
+
+## Make light the default
+
+Axerity defaults to dark. To default to light, change two spots:
+
+```ts title="src/lib/state/theme.svelte.ts"
+class ThemeState {
+	preference = $state<ThemePreference>('light'); // was 'dark'
+}
+```
+
+```html title="src/app.html"
+<script>
+	const pref = localStorage.getItem('axerity-theme') ?? 'light'; // was 'dark'
+</script>
+```
+
+The second one is the no-flash script that sets the theme **before paint**, keep
+it in sync with the default or the page will flash on load.
+
+## Add your own token
+
+Need a new semantic color, say a highlight background? Add it in three steps:
+
+```css title="src/routes/layout.css"
+:root {
+	--highlight: oklch(0.95 0.05 95);
+}
+.dark {
+	--highlight: oklch(0.3 0.05 95);
+}
+@theme inline {
+	--color-highlight: var(--highlight); /* now usable as bg-highlight, text-highlight */
+}
+```
+
+## A whole new named theme
+
+The default light/dark live on `:root` and `.dark`. To ship **additional**
+themes (e.g. a "sepia" reading mode), override the tokens under a `data-theme`
+attribute and set it on `<html>`:
+
+```css title="src/routes/layout.css"
+[data-theme='sepia'] {
+	--bg: oklch(0.96 0.02 85);
+	--surface: oklch(0.98 0.015 85);
+	--fg: oklch(0.28 0.03 70);
+	--accent: oklch(0.5 0.12 50);
+	/* …override the rest of the semantic tokens… */
+}
+```
+
+```ts title="apply it"
+document.documentElement.dataset.theme = 'sepia';
+```
+
+Because components read only semantic tokens, a complete new theme is just a new
+block of variable values, no component changes.
+
+<Callout type="tip">
+
+This is exactly how the default `.dark` block works. A named theme is the same
+idea with a different selector.
+
+</Callout>
+
+## Restyle the prose
+
+Rendered Markdown is styled under `.doc-content` in `src/routes/layout.css`,
+headings, links, tables, blockquotes, inline code. Adjust spacing, sizes, or
+weights there to change how content reads. For example, tighten heading rhythm:
+
+```css title="src/routes/layout.css"
+.doc-content h2 {
+	margin-top: 2rem;
+	font-size: 1.4rem;
+}
+```
+
+<Callout type="warning">
+
+Keep edits in `.doc-content` and the token blocks. Touching individual component
+files is rarely needed, and makes future updates harder to merge.
+
+</Callout>

package/src/content/demo/theming/code.md

@@ -0,0 +1,66 @@
+---
+title: Code blocks
+description: Change the syntax-highlighting theme.
+icon: code
+---
+
+<script>
+	import { Callout } from '$lib';
+</script>
+
+# Code block themes
+
+Code is highlighted with [Shiki](https://shiki.style) using a **dual theme**,
+one for light, one for dark, configured in `mdsvex.config.js`.
+
+```js title="mdsvex.config.js"
+const themes = { light: 'github-light', dark: 'vesper' };
+```
+
+Pick any [bundled Shiki theme](https://shiki.style/themes) for each side:
+
+```js title="mdsvex.config.js"
+const themes = { light: 'min-light', dark: 'github-dark-default' };
+```
+
+<Callout type="warning">
+
+`mdsvex.config.js` is read at build time, so **restart the dev server** after
+changing themes, Vite doesn't hot-reload it.
+
+</Callout>
+
+## Block background
+
+Shiki inlines each theme's own background, but Axerity overrides it with the
+`--surface-raised` token so code blocks match cards and panels. That rule is in
+`src/routes/layout.css`:
+
+```css title="src/routes/layout.css"
+.doc-content pre.shiki {
+	background-color: var(--surface-raised) !important;
+}
+```
+
+Remove the override if you'd rather keep the Shiki theme's native background.
+
+## Languages
+
+Grammars are preloaded in `mdsvex.config.js`. Add any language you use:
+
+```js title="mdsvex.config.js"
+const langs = ['svelte', 'typescript', 'javascript', 'json', 'bash', 'css', 'python'];
+```
+
+Unlisted languages fall back to plain text.
+
+## Fence options
+
+Authors get titles, line highlighting, and line numbers out of the box:
+
+````md
+```ts title="example.ts" {2} showLineNumbers
+const a = 1;
+const b = 2; // highlighted
+```
+````

package/src/content/demo/theming/colors.md

@@ -0,0 +1,103 @@
+---
+title: Colors
+description: Change the accent and surface palette.
+icon: palette
+---
+
+<script>
+	import { Callout } from '$lib';
+</script>
+
+# Colors
+
+All colors are defined as [oklch](https://oklch.com) values on `:root` and
+`.dark` in `src/routes/layout.css`. oklch is `lightness chroma hue`, it keeps
+colors perceptually even, which makes building a balanced scale much easier.
+
+## From the config
+
+You do not have to touch CSS to set a brand color. Add a `brand` block to
+`axerity.json` and it overrides the active theme's accent and corner radius in
+both light and dark:
+
+```json title="axerity.json"
+{
+	"brand": {
+		"accent": "#6d5efc",
+		"radius": "0.75rem"
+	}
+}
+```
+
+`accent` takes any CSS color (hex, `rgb()`, `oklch()`). `radius` sets the base
+corner rounding. For anything beyond the accent, edit the tokens below.
+
+## Change the accent
+
+The accent drives links, active sidebar items, focus states, and highlights.
+Set `--accent` (and its hover / contrast pair) in both themes:
+
+```css title="src/routes/layout.css"
+:root {
+	--accent: oklch(0.55 0.22 264); /* blue */
+	--accent-hover: oklch(0.62 0.2 264);
+	--accent-contrast: oklch(0.99 0 0); /* text on a solid accent */
+}
+
+.dark {
+	--accent: oklch(0.7 0.16 264); /* lighter on dark */
+	--accent-hover: oklch(0.76 0.14 264);
+	--accent-contrast: oklch(0.18 0.02 264);
+}
+```
+
+<Callout type="tip">
+
+Use a **lighter, less saturated** accent in dark mode than in light, high
+chroma on a dark background is harsh. Bumping lightness by ~0.15 is a good start.
+
+</Callout>
+
+## Change the surfaces
+
+Surfaces and text are neutral by default (`chroma 0`). To tint the whole UI,
+say, a cool slate, give every neutral token a small chroma at a shared hue:
+
+```css title="src/routes/layout.css"
+.dark {
+	--bg: oklch(0.16 0.015 264);
+	--bg-subtle: oklch(0.2 0.018 264);
+	--surface: oklch(0.21 0.018 264);
+	--surface-raised: oklch(0.24 0.02 264);
+	--fg: oklch(0.96 0.01 264);
+	--fg-muted: oklch(0.72 0.015 264);
+	--border: oklch(0.28 0.015 264);
+}
+```
+
+Keep the **lightness** values close to the defaults, they're tuned for
+contrast. Adjust **chroma** and **hue** to set the mood.
+
+## The brand gradient
+
+The signature gradient (used for accents and marks) is one variable:
+
+```css title="src/routes/layout.css"
+:root {
+	--brand-gradient: linear-gradient(135deg, oklch(0.55 0.22 264), oklch(0.6 0.2 300));
+}
+```
+
+## Semantic colors
+
+Component accent colors (Callout variants, API method badges) are intentionally
+**not** tied to `--accent`, they stay semantic (green = success, red = danger)
+so meaning survives any accent change. Adjust them in their components if needed:
+`src/lib/components/kit/Callout.svelte` and `…/api/Endpoint.svelte`.
+
+<Callout type="warning">
+
+Always check both light **and** dark after a color change, a value that reads
+well on one can fail on the other.
+
+</Callout>

package/src/content/demo/theming/index.md

@@ -0,0 +1,88 @@
+---
+title: Theming overview
+description: How Axerity's design-token system works.
+icon: palette
+---
+
+<script>
+	import { Callout } from '$lib';
+</script>
+
+# Theming
+
+Axerity is themed entirely through **CSS custom properties** (design tokens). Every
+color, font, radius, and layout rail is a token, components never reference raw
+values, so changing a handful of variables re-themes the whole site, light and
+dark, in one place.
+
+Everything lives in **`src/routes/layout.css`**.
+
+## The two layers
+
+Theming is split into two layers:
+
+1. **Semantic tokens**, `--bg`, `--fg`, `--accent`, `--border`… defined on
+   `:root` (light) and overridden on `.dark` (dark). This is what you edit.
+2. **Tailwind bridge**, an `@theme inline` block maps those tokens onto Tailwind
+   utilities (`bg-bg`, `text-fg`, `border-border`, `rounded-lg`, …) so components
+   can use them as normal classes.
+
+```css title="src/routes/layout.css"
+:root {
+	--bg: oklch(1 0 0);
+	--fg: oklch(0.205 0 0);
+	--accent: oklch(0.205 0 0);
+	/* …all light values… */
+}
+
+.dark {
+	--bg: oklch(0.145 0 0);
+	--fg: oklch(0.985 0 0);
+	--accent: oklch(0.922 0 0);
+	/* …dark overrides… */
+}
+
+@theme inline {
+	--color-bg: var(--bg);
+	--color-fg: var(--fg);
+	--color-accent: var(--accent);
+	/* …exposes bg-bg / text-fg / text-accent / … to Tailwind… */
+}
+```
+
+## The semantic tokens
+
+| Token               | Used for                                 |
+| ------------------- | ---------------------------------------- |
+| `--bg`              | Page background                          |
+| `--bg-subtle`       | Muted background (headers, hover)        |
+| `--surface`         | Card / panel background                  |
+| `--surface-raised`  | Elevated surfaces (code blocks)          |
+| `--fg`              | Primary text                             |
+| `--fg-muted`        | Body / secondary text                    |
+| `--fg-subtle`       | Tertiary text, labels                    |
+| `--border`          | Default borders                          |
+| `--border-strong`   | Emphasized borders                       |
+| `--accent`          | Accent, links, active states, highlights |
+| `--accent-hover`    | Accent hover state                       |
+| `--accent-contrast` | Text on a solid accent background        |
+| `--brand-gradient`  | The signature gradient                   |
+
+<Callout type="tip">
+
+Because components only use these tokens, you almost never edit a component to
+re-theme, you edit the tokens.
+
+</Callout>
+
+## The default theme
+
+Out of the box Axerity ships a **neutral (shadcn-style)** theme: pure grayscale
+surfaces, a monochrome accent, and **dark by default**. The next pages show how
+to make it yours.
+
+- [Colors](/theming/colors), accent and surfaces
+- [Typography](/theming/typography), fonts
+- [Layout](/theming/layout), widths and rails
+- [Code blocks](/theming/code), syntax themes
+- [Advanced](/theming/advanced), radius, custom tokens, full themes

package/src/content/demo/theming/layout.md

@@ -0,0 +1,71 @@
+---
+title: Layout
+description: Control widths, rails, and the page shell.
+icon: layout-grid
+---
+
+<script>
+	import { Callout } from '$lib';
+</script>
+
+# Layout
+
+## Flat vs boxed
+
+The overall shell has two modes, set in `src/lib/config/site.ts`:
+
+```ts title="src/lib/config/site.ts"
+export const site: SiteConfig = {
+	name: 'Axerity',
+	layout: 'flat' // 'flat' (full-bleed, sidebar at the edge) or 'boxed' (centered)
+};
+```
+
+- **`flat`** _(default)_, the sidebar sits flush at the left edge and the shell
+  spans the viewport.
+- **`boxed`**, the whole shell (navbar + columns) centers in a max-width
+  container on wide screens.
+
+## Layout rails
+
+The widths of the shell's columns are tokens in the `@theme` block. Tune them to
+taste:
+
+```css title="src/routes/layout.css"
+@theme inline {
+	--spacing-sidebar: 17rem; /* left navigation */
+	--spacing-toc: 15rem; /* right table of contents */
+	--spacing-header: 4rem; /* sticky navbar height */
+	--spacing-content: 48rem; /* reading width of doc pages */
+}
+```
+
+`--spacing-content` is the most impactful, it sets the line length of prose.
+17rem ≈ 272px sidebar, 48rem ≈ 768px content.
+
+## The API layout
+
+Pages with `layout: api` in their frontmatter switch to a **wide, TOC-less**
+two-column layout (content on the left, sticky request/response samples on the
+right):
+
+```md title="content/docs/api/get-user.md"
+---
+title: Get a user
+layout: api
+---
+```
+
+<Callout type="tip">
+
+Set `defaultOpen: true` in a folder's `meta.json` to keep that sidebar group
+expanded by default, handy for an API section.
+
+</Callout>
+
+## The three columns
+
+The shell is sidebar / content / table-of-contents. The TOC auto-hides below the
+`xl` breakpoint and in API mode; the sidebar collapses into a drawer below `lg`.
+The structure lives in `src/lib/components/docs/DocsLayout.svelte` if you need to
+restructure it.

package/src/content/demo/theming/meta.json

@@ -0,0 +1,5 @@
+{
+	"title": "Theming",
+	"icon": "palette",
+	"pages": ["index", "themes", "colors", "typography", "layout", "code", "advanced"]
+}

package/src/content/demo/theming/themes.md

@@ -0,0 +1,99 @@
+---
+title: Themes
+description: Eight built-in presets inspired by well-known docs.
+icon: palette
+---
+
+# Themes
+
+A theme is a complete palette: backgrounds, text, borders, and an accent, with a
+matching dark mode. Pick one in `axerity.json`:
+
+```json
+{
+	"theme": "stripe"
+}
+```
+
+Leave it out (or use `"neutral"`) for the default grayscale look. The theme is
+applied on the server, so there is no flash on load, and dark mode works with
+every preset.
+
+## Your own brand
+
+Not tied to the presets. Set `brand` to drop in your own accent and corners on
+top of any `theme` (the accent drives links, active items, buttons, and the
+sidebar tint):
+
+```json
+{
+	"theme": "neutral",
+	"brand": {
+		"accent": "#ff5722",
+		"radius": "0.75rem"
+	}
+}
+```
+
+| Field            | Description                                |
+| ---------------- | ------------------------------------------ |
+| `accent`         | Accent color, any CSS color                |
+| `accentDark`     | Accent in dark mode (defaults to `accent`) |
+| `accentContrast` | Text color on the accent (default white)   |
+| `radius`         | Base corner radius, e.g. `0.5rem`          |
+
+Brand values win over the preset, so `neutral` plus your accent gives a clean,
+on-brand site. Pick a colored preset for a fuller reskin.
+
+## Presets
+
+Each preset is tuned after a product's documentation. Set the `theme` value to
+the name on the left.
+
+| Theme       | Accent                                                                                                                                               | Feel                                  |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `neutral`   | <span style="display:inline-block;width:14px;height:14px;border-radius:9999px;background:oklch(0.4 0 0);vertical-align:middle"></span> Grayscale     | Quiet monochrome, the default         |
+| `stripe`    | <span style="display:inline-block;width:14px;height:14px;border-radius:9999px;background:oklch(0.55 0.23 274);vertical-align:middle"></span> Indigo  | Airy and light with soft corners      |
+| `vercel`    | <span style="display:inline-block;width:14px;height:14px;border-radius:9999px;background:oklch(0.18 0 0);vertical-align:middle"></span> Black/white  | Maximum contrast, sharp corners       |
+| `linear`    | <span style="display:inline-block;width:14px;height:14px;border-radius:9999px;background:oklch(0.55 0.16 277);vertical-align:middle"></span> Violet  | Cool grays, dense, great in dark      |
+| `supabase`  | <span style="display:inline-block;width:14px;height:14px;border-radius:9999px;background:oklch(0.76 0.16 162);vertical-align:middle"></span> Green   | Dark-first with a bright green accent |
+| `github`    | <span style="display:inline-block;width:14px;height:14px;border-radius:9999px;background:oklch(0.52 0.18 256);vertical-align:middle"></span> Blue    | Primer blue and the system font       |
+| `tailwind`  | <span style="display:inline-block;width:14px;height:14px;border-radius:9999px;background:oklch(0.68 0.15 233);vertical-align:middle"></span> Sky     | Slate grays and rounded corners       |
+| `mintlify`  | <span style="display:inline-block;width:14px;height:14px;border-radius:9999px;background:oklch(0.62 0.16 150);vertical-align:middle"></span> Emerald | Friendly, light, and rounded          |
+| `anthropic` | <span style="display:inline-block;width:14px;height:14px;border-radius:9999px;background:oklch(0.62 0.13 42);vertical-align:middle"></span> Clay     | Warm accent on an ivory page          |
+
+## Layout
+
+The `theme` controls color, type, and corners. The `layout` controls the shape
+of the page and is set separately:
+
+```json
+{
+	"theme": "stripe",
+	"layout": "boxed"
+}
+```
+
+- `flat` puts the sidebar flush against the left edge and fills the screen.
+- `boxed` centers the whole site in a max-width container on wide screens.
+
+Mix and match. Stripe and Tailwind feel at home boxed; Vercel and Linear suit
+the flat, full-width look.
+
+## Sidebar
+
+Choose how the sidebar is presented with `sidebar.variant`:
+
+```json
+{
+	"sidebar": { "variant": "floating" }
+}
+```
+
+- `flush` is the default: a tinted panel against the edge with a divider.
+- `card` insets the sidebar as a bordered, rounded panel.
+- `floating` detaches it into a rounded, shadowed card that floats in the
+  margin.
+
+All three pick up the theme's accent tint, so a floating Supabase sidebar reads
+green while a floating Stripe one reads indigo.