@axerity/cli 0.1.0 → 0.1.2

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import {
 	cpSync,
@@ -20,9 +21,14 @@ const isEngineRepo = userRoot === engineRoot;
 
 const symlinkType = process.platform === 'win32' ? 'junction' : 'dir';
 
-// 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 require = createRequire(import.meta.url);
+function viteBin() {
+	const pkgPath = require.resolve('vite/package.json');
+	const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+	const rel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin.vite;
+	return resolve(dirname(pkgPath), rel);
+}
+
 const ENGINE_DOCS = join(engineRoot, 'src', 'content', 'docs');
 const ENGINE_CONFIG = join(engineRoot, 'axerity.json');
 const ENGINE_STATIC = join(engineRoot, 'static');
@@ -38,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;
@@ -66,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');
@@ -106,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) => {
@@ -130,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;
@@ -152,8 +149,7 @@ function streamBuild(child) {
 }
 
 function runEngine(sub, extra, { mounted, onSuccess }) {
-	const viteEntry = join(engineRoot, 'node_modules', 'vite', 'bin', 'vite.js');
-	const child = spawn(process.execPath, [viteEntry, sub, ...extra], {
+	const child = spawn(process.execPath, [viteBin(), sub, ...extra], {
 		cwd: engineRoot,
 		stdio: ['inherit', 'pipe', 'pipe'],
 		env: {
@@ -165,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 = () => {
@@ -190,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 });
@@ -271,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');
@@ -287,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.0",
+  "version": "0.1.2",
   "description": "A documentation site generator built with Svelte.",
   "type": "module",
   "license": "MIT",

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
 });