@axerity/cli 0.1.0

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

@@ -0,0 +1,46 @@
+---
+title: CLI
+description: The axerity command.
+icon: code
+---
+
+# CLI
+
+The `axerity` command scaffolds, runs, and builds your site. It carries the whole
+engine, so your project only holds content and config.
+
+## Commands
+
+```bash
+axerity init [dir]   # scaffold a new site (defaults to the current folder)
+axerity dev          # start the dev server
+axerity build        # build the static site
+axerity preview      # preview the production build
+```
+
+Run them with `npx axerity <command>`, or install globally with
+`npm install -g axerity` and call `axerity` directly.
+
+## init
+
+`axerity init my-docs` creates a starter site: an `axerity.json`, a `docs/`
+folder with a couple of pages and a `meta.json`, and a `.gitignore`. Leave off
+the folder name to scaffold into the current directory.
+
+## dev
+
+`axerity dev` serves your site with live reload. Editing a Markdown file or
+`axerity.json` updates the browser immediately. Pass through any Vite flag, for
+example `axerity dev --port 4000`.
+
+## build
+
+`axerity build` produces a static site. Every page is prerendered to HTML, and
+the search index, `llms.txt`, sitemap, RSS feed, and OpenGraph images are all
+written out, ready to host anywhere.
+
+## How it works
+
+The CLI never touches your content. It assembles a hidden `.axerity` workspace
+that pairs the packaged engine with your `docs/` folder and `axerity.json`, then
+runs Vite there. Add `.axerity` to your `.gitignore`; `init` does this for you.

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

@@ -0,0 +1,105 @@
+---
+title: Deployment
+description: Build and host your docs.
+icon: rocket
+---
+
+# Deployment
+
+`axerity build` writes a plain folder of static files to `build/`. Every page is
+prerendered to HTML, and the search index, `.md` URLs, `llms.txt`, sitemap, RSS
+feed, and OpenGraph images are all written out. Any static host can serve it, no
+server required.
+
+```bash
+axerity build   # -> build/
+```
+
+Most hosts write `.html` files (`installation.html`) but link to clean URLs
+(`/installation`), so the one thing to get right per host is **clean URL**
+handling. Each guide below covers it.
+
+## Vercel
+
+Add a `vercel.json` so Vercel serves the static output instead of looking for a
+SvelteKit server build:
+
+```json title="vercel.json"
+{
+	"framework": null,
+	"buildCommand": "axerity build",
+	"outputDirectory": "build",
+	"cleanUrls": true
+}
+```
+
+Push the repo and Vercel does the rest. If pages still 404, open Project →
+Settings and set the Framework Preset to **Other**.
+
+## Cloudflare Pages
+
+In the Pages project settings:
+
+- **Build command:** `npx axerity build`
+- **Build output directory:** `build`
+- **Framework preset:** None
+
+Cloudflare serves clean URLs automatically.
+
+## Netlify
+
+```toml title="netlify.toml"
+[build]
+  command = "npx axerity build"
+  publish = "build"
+```
+
+Netlify serves clean URLs (pretty URLs) by default.
+
+## GitHub Pages
+
+Build, then publish the `build/` folder (for example with a GitHub Action that
+runs `npx axerity build` and uploads `build/` as the Pages artifact).
+
+Project sites are served from `https://<user>.github.io/<repo>/`, a sub-path, so
+set the base in `axerity.json`:
+
+```json title="axerity.json"
+{
+	"basePath": "/<repo>"
+}
+```
+
+User and organization sites (served from the domain root) need no `basePath`.
+
+## Nginx
+
+Serve `build/` and fall back to the `.html` file for clean URLs:
+
+```nginx
+server {
+	listen 80;
+	server_name docs.example.com;
+	root /var/www/build;
+
+	location / {
+		try_files $uri $uri.html $uri/index.html /404.html;
+	}
+}
+```
+
+## Caddy
+
+```caddy
+docs.example.com {
+	root * /var/www/build
+	try_files {path} {path}.html {path}/index.html
+	file_server
+}
+```
+
+## Any other host
+
+Upload the contents of `build/` and point the host at it. Configure two things if
+you can: serve `<name>.html` for `/<name>` (clean URLs), and use `404.html` as
+the not-found page.

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

@@ -0,0 +1,92 @@
+---
+title: The config file
+description: Everything you set in axerity.json.
+icon: sliders
+---
+
+# The config file
+
+The whole site is configured from one file at the project root: `axerity.json`.
+You never edit code to change the site. Drop in Markdown, set up your
+`meta.json` files for ordering, and edit `axerity.json` for everything global.
+
+## Editor autocomplete
+
+The repo ships a JSON schema. Point your config at it on the first line and your
+editor gives you autocomplete and validation for every field:
+
+```json title="axerity.json"
+{
+	"$schema": "./axerity.schema.json"
+}
+```
+
+## A full example
+
+```json title="axerity.json"
+{
+	"$schema": "./axerity.schema.json",
+	"name": "Axerity",
+	"description": "A documentation site generator built with Svelte.",
+	"url": "https://axerity.com",
+	"github": "https://github.com/your/repo",
+	"editLink": "https://github.com/your/repo/edit/main/src/content/docs",
+	"theme": "stripe",
+	"layout": "boxed",
+	"sidebar": { "variant": "floating" },
+	"logo": { "light": "/logo-light.svg", "dark": "/logo-dark.svg" },
+	"og": { "enabled": true },
+	"banner": { "text": "v1.0 is out", "href": "/docs", "id": "v1", "dismissible": true },
+	"versions": [{ "label": "v1.0", "href": "/docs" }],
+	"dropdowns": [
+		{
+			"label": "Guides",
+			"icon": "book-open",
+			"href": "/docs",
+			"match": "/docs",
+			"tabs": [{ "title": "Documentation", "href": "/docs", "match": "/docs" }]
+		}
+	],
+	"sidebarLinks": [{ "title": "Support", "href": "https://example.com/support" }],
+	"social": [{ "icon": "rss", "href": "/rss.xml" }],
+	"footer": { "note": "Built with Axerity", "links": [{ "title": "Status", "href": "/status" }] },
+	"analytics": { "plausible": "axerity.com" },
+	"topNav": [{ "title": "Docs", "href": "/docs" }]
+}
+```
+
+## Fields
+
+| Field          | Type                     | What it does                                                                                |
+| -------------- | ------------------------ | ------------------------------------------------------------------------------------------- |
+| `name`         | string                   | Site name, used in the page title and navbar                                                |
+| `description`  | string                   | Site description, used for SEO and `llms.txt`                                               |
+| `url`          | string                   | Canonical site URL; enables absolute links in sitemap, RSS, and OpenGraph                   |
+| `github`       | string                   | Repo URL, shown as the GitHub icon in the navbar and footer                                 |
+| `editLink`     | string                   | Base URL for the "Edit this page" link; the source path is appended                         |
+| `theme`        | string                   | A built-in [theme](/theming/themes) preset                                                  |
+| `brand`        | object                   | Custom `{ accent, radius }` that override the theme. See [Colors](/theming/colors)          |
+| `layout`       | string                   | `flat` (default) or `boxed`. See [Layouts](/configuration/layouts)                          |
+| `basePath`     | string                   | Serve the whole site under a sub-path like `/docs`. Empty (default) is the root             |
+| `sidebar`      | object                   | Sidebar appearance: `{ "variant": "flush" \| "card" \| "floating" }`                        |
+| `logo`         | object                   | Navbar logo `{ light, dark, alt, href }`. Local SVGs are inlined                            |
+| `og`           | object                   | Per-page OpenGraph image generation `{ enabled, background, foreground, … }`                |
+| `ogImage`      | string                   | Static OG image path, used when `og.enabled` is off                                         |
+| `banner`       | object                   | Announcement bar `{ text, href, id, dismissible }`                                          |
+| `analytics`    | object                   | `{ plausible, googleAnalytics }` scripts injected on every page                             |
+| `topNav`       | array                    | Fallback top nav links when no dropdowns are set                                            |
+| `versions`     | array                    | Versions shown in the navbar version switcher                                               |
+| `dropdowns`    | array                    | Areas that swap the whole sidebar. See [Navigation](/configuration/navigation)              |
+| `openapi`      | string, object, or array | Generate an API reference from an OpenAPI spec. See [API reference](/configuration/openapi) |
+| `sidebarLinks` | array                    | Links pinned to the bottom of the sidebar                                                   |
+| `social`       | array                    | Social links shown in the footer `{ icon, href, label }`                                    |
+| `footer`       | object                   | Footer `{ note, links }`                                                                    |
+
+Every field except `name` and `topNav` is optional. Leave a field out and the
+related UI does not render.
+
+## Icons
+
+Anywhere a config field takes an `icon`, use a [Lucide](https://lucide.dev) icon
+name in kebab case, such as `book-open`, `credit-card`, or `git-branch`. Any
+Lucide icon works, so you never register icons by hand.

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

@@ -0,0 +1,51 @@
+---
+title: Layouts
+description: Page width and the API layout.
+icon: layout-grid
+---
+
+# Layouts
+
+## Flat and boxed
+
+The whole shell has two modes, set with `layout` in `axerity.json`:
+
+```json title="axerity.json"
+{
+	"layout": "flat"
+}
+```
+
+- `flat` (default) is full width. The sidebar sits at the left edge.
+- `boxed` centers the shell in a max-width container on wide screens.
+
+## The doc layout
+
+Normal pages use the three column layout: sidebar on the left, content in the
+middle, and a table of contents on the right. The table of contents tracks your
+scroll position. It hides on narrow screens, and the sidebar becomes a drawer.
+
+## The API layout
+
+Set `layout: api` in a page's frontmatter to switch to the API layout. It is
+wider, drops the table of contents, and gives you a two column layout with the
+content on the left and sticky request and response examples on the right.
+
+```md
+---
+title: Create a user
+layout: api
+---
+```
+
+See the [API reference components](/api/pet/pet-object) for what you can
+put on these pages.
+
+## On every page
+
+Both layouts include a few things automatically:
+
+- A breadcrumb trail above the title.
+- A copy page button. See [AI and LLMs](/configuration/ai).
+- Previous and next links at the bottom.
+- A footer.

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

@@ -0,0 +1,5 @@
+{
+	"title": "Configuration",
+	"icon": "sliders",
+	"pages": ["index", "navigation", "layouts", "search", "openapi", "ai", "cli", "deployment"]
+}

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

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

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

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

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