@axerity/cli 0.1.1 → 0.1.3

package/README.md

@@ -1 +1,97 @@
 # Axerity
+
+A documentation site generator built with SvelteKit. Write Markdown, configure
+one JSON file, and ship a fast static site.
+
+## Quick start
+
+```sh
+pnpm dlx @axerity/cli init mydocs
+cd mydocs
+pnpm dlx @axerity/cli dev
+```
+
+That scaffolds a content-only project and starts a live dev server at
+`http://localhost:5173`.
+
+```
+mydocs/
+  axerity.json     # all configuration
+  docs/            # your Markdown
+    meta.json      # ordering and icons per folder
+    index.md
+    quickstart.md
+```
+
+## Install
+
+Run it without installing:
+
+```sh
+pnpm dlx @axerity/cli <command>
+```
+
+Or add it to a project so the version is pinned and reproducible:
+
+```sh
+pnpm add -D @axerity/cli
+```
+
+```json
+{
+  "scripts": {
+    "dev": "axerity dev",
+    "build": "axerity build",
+    "preview": "axerity preview"
+  }
+}
+```
+
+## Commands
+
+| Command           | What it does                          |
+| ----------------- | ------------------------------------- |
+| `axerity init`    | Scaffold a new docs site              |
+| `axerity dev`     | Start the dev server with live reload |
+| `axerity build`   | Build a static site into `./build`    |
+| `axerity preview` | Serve the production build locally    |
+
+The build output is a plain static site you can host anywhere: Vercel, Netlify,
+Cloudflare, GitHub Pages, nginx, or any static host.
+
+## Features
+
+- Markdown with a built in component kit: callouts, cards, tabs, steps,
+  accordions, code groups, badges, trees, frames, and more
+- API references generated from an OpenAPI spec, plus webhook and WebSocket
+  components
+- Versioned content with a switcher that follows the reader across versions
+- Themes, custom brand colors, and full white labelling from `axerity.json`
+- Build time search, an RSS feed, sitemap, `llms.txt`, and dynamic OpenGraph
+  images
+- Mermaid diagrams, Twoslash type hovers, and syntax highlighting
+
+## Configuration
+
+Everything global lives in `axerity.json`. A few of the common keys:
+
+```json
+{
+  "$schema": "https://axerity.com/axerity.schema.json",
+  "name": "My Docs",
+  "theme": "neutral",
+  "openapi": "./openapi.json",
+  "topNav": [{ "title": "Docs", "href": "/" }]
+}
+```
+
+Point `$schema` at the bundled JSON schema for autocomplete and validation in
+your editor.
+
+## Requirements
+
+Node.js 24 or newer.
+
+## License
+
+MIT

package/bin/axerity.js

@@ -29,9 +29,6 @@ function viteBin() {
 	return resolve(dirname(pkgPath), rel);
 }
 
-// The engine runs in place, from its own install with its real node_modules. The
-// user's project is mounted into a handful of gitignored paths for a single run,
-// so nothing the engine tracks is ever touched — clean exit, Ctrl-C, or crash.
 const ENGINE_DOCS = join(engineRoot, 'src', 'content', 'docs');
 const ENGINE_CONFIG = join(engineRoot, 'axerity.json');
 const ENGINE_STATIC = join(engineRoot, 'static');
@@ -47,16 +44,12 @@ function findContentDir() {
 	return null;
 }
 
-/** Reset the engine's own demo site into the mount points (for `axerity` runs
- *  from inside the engine repo). `pnpm dev` does this via its pre-scripts. */
 function prepareEngine() {
 	spawnSync(process.execPath, [join(engineRoot, 'scripts', 'prepare-engine.mjs')], {
 		stdio: 'inherit'
 	});
 }
 
-/** Copy local specs into a gitignored folder and rewrite the config to point at
- *  them, so the user's spec paths resolve without touching the engine tree. */
 function mountSpecs(config) {
 	const rewrite = (source) => {
 		const spec = typeof source === 'string' ? source : source.spec;
@@ -75,19 +68,15 @@ function mountSpecs(config) {
 }
 
 function mount(contentDir) {
-	// Content -> the path the engine globs, as symlinks so generated pages (an API
-	// reference) can sit alongside without touching the user's repo.
 	rmSync(ENGINE_DOCS, { recursive: true, force: true });
 	mkdirSync(ENGINE_DOCS, { recursive: true });
 	for (const entry of readdirSync(contentDir)) {
 		symlinkSync(join(contentDir, entry), join(ENGINE_DOCS, entry), symlinkType);
 	}
 
-	// Config (with local spec paths rewritten into the gitignored specs folder).
 	const config = JSON.parse(readFileSync(join(userRoot, 'axerity.json'), 'utf8'));
 	writeFileSync(ENGINE_CONFIG, JSON.stringify(mountSpecs(config), null, '\t'));
 
-	// Assets: engine defaults overlaid with the user's public/ folder.
 	rmSync(ASSETS_DIR, { recursive: true, force: true });
 	cpSync(ENGINE_STATIC, ASSETS_DIR, { recursive: true });
 	const userPublic = join(userRoot, 'public');
@@ -115,7 +104,7 @@ const banner = (sub) => process.stdout.write(`\n  ${mark} ${bold('axerity')} ${d
 const NOISE =
 	/^\s*(VITE v|➜|press h|ready in|Local:|Network:|\[vite\].*(optimiz|dependencies)|\[optimizer\]|Forced re-opt|watching for file changes|use --host)/i;
 
-function streamServer(child, sub) {
+function streamServer(child) {
 	let shown = false;
 	let buffer = '';
 	const onData = (chunk) => {
@@ -139,7 +128,6 @@ function streamServer(child, sub) {
 	child.stderr.on('data', onData);
 }
 
-/** A build: silent spinner on success, full captured output only on failure. */
 function streamBuild(child) {
 	const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 	let i = 0;
@@ -173,7 +161,7 @@ function runEngine(sub, extra, { mounted, onSuccess }) {
 	});
 
 	banner(sub);
-	const build = sub === 'build' ? streamBuild(child) : (streamServer(child, sub), null);
+	const build = sub === 'build' ? streamBuild(child) : (streamServer(child), null);
 
 	let cleaned = false;
 	const cleanup = () => {
@@ -198,7 +186,6 @@ function runEngine(sub, extra, { mounted, onSuccess }) {
 }
 
 function run(sub, extra) {
-	// Inside the engine repo: serve its own demo site.
 	if (isEngineRepo) {
 		prepareEngine();
 		return runEngine(sub, extra, { mounted: false });
@@ -246,7 +233,7 @@ function init() {
 	const files = {
 		'axerity.json': `${JSON.stringify(
 			{
-				$schema: 'https://axerity.com/axerity.schema.json',
+				$schema: 'https://unpkg.com/@axerity/cli/axerity.schema.json',
 				name: 'My Docs',
 				description: 'Documentation built with Axerity.',
 				theme: 'neutral',
@@ -279,9 +266,11 @@ function init() {
 	console.log('  axerity dev');
 }
 
+const pkgVersion = () =>
+	JSON.parse(readFileSync(join(engineRoot, 'package.json'), 'utf8')).version;
+
 function help() {
-	const { version } = JSON.parse(readFileSync(join(engineRoot, 'package.json'), 'utf8'));
-	console.log(`Axerity ${version} — a documentation site generator\n`);
+	console.log(`Axerity ${pkgVersion()} — a documentation site generator\n`);
 	console.log('Usage: axerity <command>\n');
 	console.log('Commands:');
 	console.log('  init [dir]   Scaffold a new docs site');
@@ -295,6 +284,11 @@ const command = process.argv[2];
 const extra = process.argv.slice(3);
 
 switch (command) {
+	case '--version':
+	case '-v':
+	case 'version':
+		console.log(pkgVersion());
+		break;
 	case 'init':
 		init();
 		break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axerity/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A documentation site generator built with Svelte.",
   "type": "module",
   "license": "MIT",
@@ -59,6 +59,7 @@
     "@tailwindcss/forms": "^0.5.11",
     "@tailwindcss/typography": "^0.5.19",
     "@tailwindcss/vite": "^4.3.0",
+    "lucide": "^1.17.0",
     "mdsvex": "^0.12.7",
     "mermaid": "^11.15.0",
     "rehype-slug": "^6.0.0",

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

@@ -18,8 +18,8 @@ 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.
+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
 
@@ -35,12 +35,14 @@ 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.
+`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 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.
+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

@@ -40,7 +40,7 @@ Settings and set the Framework Preset to **Other**.
 
 In the Pages project settings:
 
-- **Build command:** `npx axerity build`
+- **Build command:** `npx @axerity/cli build`
 - **Build output directory:** `build`
 - **Framework preset:** None
 
@@ -50,7 +50,7 @@ Cloudflare serves clean URLs automatically.
 
 ```toml title="netlify.toml"
 [build]
-  command = "npx axerity build"
+  command = "npx @axerity/cli build"
   publish = "build"
 ```
 
@@ -59,7 +59,7 @@ 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).
+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`:

package/src/content/demo/installation.md

@@ -6,35 +6,52 @@ icon: download
 
 # Installation
 
-Axerity is a CLI. You do not clone or fork anything. Install it, scaffold a site,
-and start writing Markdown.
+Axerity is a CLI. You do not clone or fork anything. Run it, scaffold a site, and
+start writing Markdown.
 
 ## Requirements
 
-- Node.js 20 or newer
+- Node.js 24 or newer
 
 ## Create a site
 
 Scaffold a new site with `init`, then start the dev server:
 
 ```bash
-npx axerity init my-docs
+pnpm dlx @axerity/cli init my-docs
 cd my-docs
-npx axerity dev
+pnpm dlx @axerity/cli dev
 ```
 
-Your site is running at `http://localhost:5173`. Or install it globally and drop
-the `npx`:
+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
-npm install -g axerity
-axerity init my-docs
+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 just your content and one config file. Everything else lives in the
-package:
+A site is your content and one config file:
 
 ```
 my-docs/
@@ -44,6 +61,6 @@ my-docs/
 ```
 
 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).
+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/lib/components/DynamicIcon.svelte

@@ -1,8 +1,8 @@
 <script lang="ts" module>
-	import type { Component } from 'svelte';
-	import * as icons from '@lucide/svelte';
+	import { icons } from 'lucide';
 
-	const registry = icons as unknown as Record<string, Component>;
+	type IconNode = [string, Record<string, string | number>][];
+	const registry = icons as unknown as Record<string, IconNode>;
 
 	const pascal = (name: string) =>
 		name
@@ -18,9 +18,24 @@
 		class: className = ''
 	}: { name?: string; size?: number; class?: string } = $props();
 
-	const Icon = $derived(name ? registry[pascal(name)] : undefined);
+	const node = $derived(name ? registry[pascal(name)] : undefined);
 </script>
 
-{#if Icon}
-	<Icon {size} class={className} />
+{#if node}
+	<svg
+		xmlns="http://www.w3.org/2000/svg"
+		width={size}
+		height={size}
+		viewBox="0 0 24 24"
+		fill="none"
+		stroke="currentColor"
+		stroke-width="2"
+		stroke-linecap="round"
+		stroke-linejoin="round"
+		class={`lucide ${className}`}
+	>
+		{#each node as [tag, attrs], i (i)}
+			<svelte:element this={tag} {...attrs} />
+		{/each}
+	</svg>
 {/if}

package/vite.config.ts

@@ -22,7 +22,7 @@ function openapi() {
 			}
 			await generateApiDocs(openapi, 'src/content/docs');
 		} catch {
-			// theres nothing
+			return;
 		}
 	};
 	return {
@@ -42,5 +42,5 @@ function openapi() {
 
 export default defineConfig({
 	plugins: [openapi(), tailwindcss(), sveltekit()],
-	server: allow ? { fs: { allow: ['.', allow] } } : undefined
+	server: allow ? { fs: { strict: false } } : undefined
 });