@axerity/cli 0.1.4 → 0.2.0

package/src/content/demo/installation.md

@@ -1,66 +0,0 @@
----
-title: Installation
-description: Get Axerity running locally in a minute.
-icon: download
----
-
-# Installation
-
-Axerity is a CLI. You do not clone or fork anything. Run it, scaffold a site, and
-start writing Markdown.
-
-## Requirements
-
-- Node.js 24 or newer
-
-## Create a site
-
-Scaffold a new site with `init`, then start the dev server:
-
-```bash
-pnpm dlx @axerity/cli init my-docs
-cd my-docs
-pnpm dlx @axerity/cli dev
-```
-
-Your site is running at `http://localhost:5173`. `pnpm dlx` runs the CLI without
-installing it. `npx @axerity/cli <command>` works the same way.
-
-## Install it
-
-For a project you build often, add it as a dev dependency so the version is
-pinned:
-
-```bash
-pnpm add -D @axerity/cli
-```
-
-Then wire up scripts in your `package.json`:
-
-```json
-{
-  "scripts": {
-    "dev": "axerity dev",
-    "build": "axerity build",
-    "preview": "axerity preview"
-  }
-}
-```
-
-Now `pnpm dev` and `pnpm build` just work, no global install or PATH setup.
-
-## Project layout
-
-A site is your content and one config file:
-
-```
-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 engine runs from its own install, so the
-only thing Axerity ever creates in your project is the `build/` folder. The
-scaffold adds it to your `.gitignore` for you.

package/src/content/demo/meta.json

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

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

@@ -1,47 +0,0 @@
----
-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

@@ -1,116 +0,0 @@
----
-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

@@ -1,66 +0,0 @@
----
-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

@@ -1,103 +0,0 @@
----
-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

@@ -1,88 +0,0 @@
----
-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

@@ -1,71 +0,0 @@
----
-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

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

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

@@ -1,99 +0,0 @@
----
-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.