@axerity/cli 0.1.4 → 0.2.0

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

@@ -1,48 +0,0 @@
----
-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 `pnpm dlx @axerity/cli <command>` (or `npx @axerity/cli <command>`),
-or add `@axerity/cli` as a dev dependency and call `axerity` through your scripts.
-
-## 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 in `build/`. 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 engine runs from its own install, not from your repo. When you run a command,
-Axerity reads your `docs/` and `axerity.json` and renders against them, then
-writes the result to `build/` in your project. Your content is the source of
-truth and nothing else in your folder is touched, so there is no workspace to
-gitignore beyond `build/`.

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

@@ -1,105 +0,0 @@
----
-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/cli build`
-- **Build output directory:** `build`
-- **Framework preset:** None
-
-Cloudflare serves clean URLs automatically.
-
-## Netlify
-
-```toml title="netlify.toml"
-[build]
-  command = "npx @axerity/cli 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/cli 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

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

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

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

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>