@axerity/cli 0.1.4 → 0.2.1

package/src/content/demo/configuration/navigation.md

@@ -1,167 +0,0 @@
----
-title: Navigation
-description: Sidebar, groups, dropdowns, tabs, and ordering.
-icon: list
----
-
-# Navigation
-
-Your sidebar is built from the folder structure under `src/content/docs`, and
-ordered by `meta.json` files. The top navigation and area switching come from
-`axerity.json`.
-
-## Folders become sidebar sections
-
-Each top-level folder under `src/content/docs` becomes a section. Files inside a
-folder become its pages. Nest a folder inside another and it becomes a
-collapsible group.
-
-```
-content/docs/
-  index.md            ->  /docs
-  installation.md     ->  /docs/installation
-  components/
-    callout.md        ->  /docs/components/callout
-  api/
-    users/
-      get-user.md     ->  /docs/api/users/get-user   (nested group)
-```
-
-## meta.json
-
-Every folder can have a `meta.json` that sets its title, icon, and the order of
-its pages.
-
-```json title="meta.json"
-{
-	"title": "Getting Started",
-	"icon": "rocket",
-	"pages": ["index", "installation", "quick-start"]
-}
-```
-
-| Field         | What it does                                                  |
-| ------------- | ------------------------------------------------------------- |
-| `title`       | The section or group label                                    |
-| `icon`        | A Lucide icon name shown next to the label                    |
-| `pages`       | Order of pages by slug. Anything left out is added at the end |
-| `defaultOpen` | For a nested group, expand it by default                      |
-
-Pages not listed in `pages` are appended in alphabetical order, so you only have
-to list the ones you care about.
-
-## Page frontmatter
-
-Each page sets its own metadata in frontmatter:
-
-```md
----
-title: Installation
-description: Get Axerity running locally.
-icon: download
-badge: New
----
-```
-
-| Field         | What it does                                           |
-| ------------- | ------------------------------------------------------ |
-| `title`       | Sidebar label and page title                           |
-| `description` | Used for SEO, search, and prev/next                    |
-| `icon`        | Lucide icon next to the sidebar link                   |
-| `badge`       | Small pill next to the title, such as `New`            |
-| `layout`      | `api` switches to the wide API layout                  |
-| `method`      | An HTTP method shown as a colored badge in the sidebar |
-
-## Dropdowns and tabs
-
-A dropdown swaps the entire sidebar. Use it to split a site into areas like
-Guides and API Reference. Each dropdown can have its own top-nav tabs.
-
-```json title="axerity.json"
-{
-	"dropdowns": [
-		{
-			"label": "Guides",
-			"icon": "book-open",
-			"href": "/docs",
-			"match": "/docs",
-			"tabs": [
-				{ "title": "Documentation", "href": "/docs", "match": "/docs" },
-				{ "title": "Components", "href": "/docs/components/callout", "match": "/docs/components" }
-			]
-		},
-		{
-			"label": "API Reference",
-			"icon": "code",
-			"href": "/docs/api/users/get-user",
-			"match": "/docs/api"
-		}
-	]
-}
-```
-
-- `href` is where the link goes.
-- `match` is the path prefix that marks a dropdown or tab as active. The longest
-  match wins, so nested areas take priority.
-- The sidebar shows only the sections under the active dropdown, and the navbar
-  shows only that dropdown's tabs.
-
-## Sidebar links
-
-Pin external links to the bottom of the sidebar. They stay in place while the
-nav scrolls, and open in a new tab.
-
-```json title="axerity.json"
-{
-	"sidebarLinks": [
-		{ "title": "Support", "href": "https://example.com/support" },
-		{ "title": "Dashboard", "href": "https://app.example.com" }
-	]
-}
-```
-
-## Versions
-
-Add a version switcher to the navbar. Each entry has a `label` and an `href`.
-
-```json title="axerity.json"
-{
-	"versions": [
-		{ "label": "v2.0", "href": "/v2" },
-		{ "label": "v1.0", "href": "/v1" }
-	]
-}
-```
-
-An `href` can point anywhere, so the simplest setup sends old versions to a
-separate site:
-
-```json title="axerity.json"
-{
-	"versions": [
-		{ "label": "v2.0", "href": "/" },
-		{ "label": "v1.0", "href": "https://v1.example.com" }
-	]
-}
-```
-
-### Versioned content
-
-When a version's `href` is a local path like `/v2`, put that version's pages in
-a matching top-level folder. Each folder is its own independent content tree
-with its own sidebar.
-
-```
-content/docs/
-  v2/
-    index.md          ->  /v2
-    installation.md   ->  /v2/installation
-  v1/
-    index.md          ->  /v1
-    installation.md   ->  /v1/installation
-```
-
-The switcher then keeps the reader on the same page across versions. Moving from
-`/v2/installation` to v1 lands on `/v1/installation` when that page exists, and
-falls back to the version's index when it does not. The site root redirects to
-the first version in the list.

package/src/content/demo/configuration/openapi.md

@@ -1,103 +0,0 @@
----
-title: API reference
-description: Generate a full API reference from an OpenAPI spec.
-icon: webhook
----
-
-<script>
-	import { Callout } from '$lib';
-</script>
-
-# API reference
-
-Point Axerity at an OpenAPI 3 spec and it generates the whole reference for you:
-a page per operation with parameters, request and response bodies, examples, auth,
-and a page per schema. The pages use the same [API components](/components/api)
-you would write by hand, so they match the rest of your docs.
-
-## Point at a spec
-
-Add an `openapi` field to `axerity.json`. The simplest form is a path or URL:
-
-```json title="axerity.json"
-{
-	"openapi": "./openapi.json"
-}
-```
-
-The spec can be a local file or a URL, in JSON or YAML:
-
-```json title="axerity.json"
-{
-	"openapi": "https://api.example.com/openapi.yaml"
-}
-```
-
-Pages are written into your content tree the next time you run `axerity dev` or
-`axerity build`, and they regenerate when a local spec changes.
-
-<Callout type="info">
-
-Generated pages are managed for you. They are added to `.gitignore` so they do
-not clutter your repo, and they are rebuilt from the spec every time.
-
-</Callout>
-
-## Choose where it lands
-
-Use the object form to set the output folder and the section title:
-
-```json title="axerity.json"
-{
-	"openapi": {
-		"spec": "./openapi.json",
-		"output": "api-reference",
-		"title": "API Reference"
-	}
-}
-```
-
-| Field    | Type   | What it does                                          |
-| -------- | ------ | ----------------------------------------------------- |
-| `spec`   | string | Local path or URL to an OpenAPI 3 spec (JSON or YAML) |
-| `output` | string | Content folder for the generated pages                |
-| `title`  | string | Section title (defaults to the spec's `info.title`)   |
-
-With `output: "api-reference"`, an operation tagged `Pet` lands at
-`/api-reference/pet/<operationId>` and each schema at
-`/api-reference/schemas/<name>`.
-
-## Group several specs
-
-Pass an array to generate more than one reference, each into its own folder:
-
-```json title="axerity.json"
-{
-	"openapi": [
-		{ "spec": "./checkout.json", "output": "checkout-api", "title": "Checkout" },
-		{ "spec": "./storefront.json", "output": "storefront-api", "title": "Storefront" }
-	]
-}
-```
-
-## Show it as a navbar tab
-
-The generated pages are ordinary docs, so you surface them like any other area:
-add a [dropdown](/configuration/navigation) that points at the output folder.
-Clicking the tab swaps the sidebar to the API reference.
-
-```json title="axerity.json"
-{
-	"dropdowns": [
-		{
-			"label": "API Reference",
-			"icon": "code",
-			"href": "/api-reference/pet/getpetbyid",
-			"match": "/api-reference"
-		}
-	]
-}
-```
-
-Set `href` to any page inside the folder (a good landing operation), and `match`
-to the folder so the tab highlights while the reader is anywhere in the reference.

package/src/content/demo/configuration/search.md

@@ -1,36 +0,0 @@
----
-title: Search
-description: Full text search across your docs.
-icon: search
----
-
-# Search
-
-Axerity ships with full text search powered by [Orama](https://orama.com). Press
-`Cmd K` or `Ctrl K`, or click the search box in the navbar, to open it.
-
-## How it works
-
-The search index is built at compile time. Every page's title, description, and
-text is collected into a single JSON file. When you open search the first time,
-that file is fetched and loaded into Orama in the browser. Searching then runs
-locally, with no server.
-
-## What is indexed
-
-- Page titles, with the highest weight.
-- Page descriptions from frontmatter.
-- The page body text, with Markdown and code stripped out.
-- The section name, shown next to each result.
-
-There is nothing to configure. Add pages and they are searchable on the next
-build.
-
-## Keyboard
-
-| Key            | Action            |
-| -------------- | ----------------- |
-| `Cmd/Ctrl + K` | Open or close     |
-| `Up` / `Down`  | Move between hits |
-| `Enter`        | Open the result   |
-| `Esc`          | Close             |

package/src/content/demo/index.md

@@ -1,59 +0,0 @@
----
-title: Introduction
-description: A documentation site generator for Svelte.
-icon: home
----
-
-<script>
-	import { Card, CardGroup, Callout } from '$lib';
-</script>
-
-# Introduction
-
-Axerity is a documentation site generator for Svelte. You write your content in
-Markdown, drop in Svelte components when you need them, and get a fast static
-site with search, navigation, and a clean theme.
-
-## What you get
-
-- File based content. Add a Markdown file and it shows up in the sidebar.
-- A `meta.json` in each folder to set titles, icons, and ordering.
-- Code blocks with syntax highlighting, copy buttons, titles, line highlighting,
-  and line numbers.
-- Components you can use right inside Markdown: callouts, cards, tabs, steps,
-  accordions, type tables, and a layout for API reference pages.
-- Light and dark themes, driven entirely by CSS variables.
-- Full text search, built at compile time.
-
-<Callout type="tip">
-
-The whole site is configured from one `axerity.json` file. Drop in Markdown,
-set up your `meta.json` files, and you never have to touch the code.
-
-</Callout>
-
-## Get started
-
-<CardGroup cols={2}>
-	<Card title="Installation" icon="download" href="/installation">
-
-Get Axerity running locally in about a minute.
-
-    </Card>
-    <Card title="Quick Start" icon="rocket" href="/quick-start">
-
-Write your first page and watch the sidebar fill in.
-
-    </Card>
-    <Card title="Components" icon="blocks" href="/components/callout">
-
-Browse the components you can use in your pages.
-
-    </Card>
-    <Card title="API Reference" icon="code" href="/api/pet/pet-object">
-
-See the layout built for documenting an API.
-
-    </Card>
-
-</CardGroup>

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
-```
-````