yaakdoc 0.1.0 → 0.2.0

package/README.md

@@ -23,3 +23,45 @@ await server.close();
 ```
 
 `yaakdoc` also re-exports `defineConfig`, `defineTheme` and `defineSnippet`.
+
+`build`, `createDevServer` and `resolveContext` take `cwd`, `configFile` and `overrides` (config values that win over the config file). They also take `exportData`, the Yaak export as an object, to use instead of reading it from a file.
+
+### Without Vite: `yaakdoc/static`
+
+`yaakdoc/static` is the part of the engine that doesn't need Vite. It loads the config and export, prepares the document, and writes a site with a theme that's already built. Use it to bundle yaakdoc into an environment where Vite can't run, the way the [Yaak plugin](https://github.com/jozsefsallai/yaakdoc/tree/master/packages/yaak-plugin) does.
+
+```ts
+import {
+  emptyOutDir,
+  resolveContext,
+  themeFromDefinition,
+  withBase,
+  writeSite,
+} from "yaakdoc/static";
+
+const context = await resolveContext({
+  exportData,
+
+  overrides: {
+    outDir: "site",
+  },
+
+  // Supply the theme instead of loading it from a package or path.
+  resolveTheme: (spec, { themeOptions }) => {
+    return themeFromDefinition(myTheme, {
+      manifest: "/themes/my-theme/theme.ts",
+      themeOptions,
+    });
+  },
+});
+
+await emptyOutDir(context.config.outDir, context.root);
+
+// ...copy the theme's prebuilt client assets into the output directory...
+await writeSite(context, {
+  render,
+  assets: withBase(assets, context.config.base),
+});
+```
+
+The theme's client assets and its `render` function come from `bundleTheme(context, outDir, { base: "./" })` in the main entry. It builds the theme with Vite once, and the `"./"` base makes the client assets work under any base path.

package/dist/cli.js

@@ -1,9 +1,35 @@
-import { a as createDevServer, n as eject, o as build, r as init, t as preview, u as VERSION } from "./preview-2YFamRKo.js";
-import { relative } from "node:path";
+import { c as VERSION } from "./site-X7q76qYf.js";
+import { a as createDevServer, n as eject, o as build, r as init, t as preview } from "./preview-Ba1BfVZV.js";
+import { ConfigError, mergeConfig } from "@yaakdoc/config";
+import { relative, resolve } from "node:path";
+import { readFileSync } from "node:fs";
 import { consola } from "consola";
 import colors from "picocolors";
 import * as p from "@clack/prompts";
 import { defineCommand, runMain } from "citty";
+//#region src/cli/overrides.ts
+/**
+* Reads the value of `--overrides`: inline JSON (starting with `{`) or the path of a JSON file. The
+* result is merged over the config file and validated together with it.
+*/
+function readOverrides(value, cwd = process.cwd()) {
+	const inline = value.trimStart().startsWith("{");
+	let text = value;
+	if (!inline) try {
+		text = readFileSync(resolve(cwd, value), "utf8");
+	} catch (error) {
+		throw new ConfigError(`Could not read overrides ${value}: ${error.message}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw new ConfigError(`Invalid JSON in ${inline ? "--overrides" : `overrides ${value}`}: ${error.message}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new ConfigError("--overrides must be a JSON object");
+	return parsed;
+}
+//#endregion
 //#region src/cli/index.ts
 const sharedArgs = {
 	export: {
@@ -39,6 +65,10 @@ const sharedArgs = {
 		type: "string",
 		alias: "w",
 		description: "Workspace to document (id or name)"
+	},
+	overrides: {
+		type: "string",
+		description: "Config values merged over the config file (a JSON file or inline JSON)"
 	}
 };
 function overridesFrom(args) {
@@ -49,14 +79,14 @@ function overridesFrom(args) {
 	if (args.base) overrides.base = args.base;
 	if (args.environment) overrides.environment = args.environment;
 	if (args.workspace) overrides.workspace = args.workspace;
-	return overrides;
+	return args.overrides ? mergeConfig(readOverrides(args.overrides), overrides) : overrides;
 }
 const rel = (path) => relative(process.cwd(), path) || ".";
 function summary(context) {
 	const requests = Object.keys(context.document.requests).length;
 	const folders = Object.keys(context.document.folders).length;
 	return [
-		`${colors.dim("Export")}       ${rel(context.exportPath)} ${colors.dim(`(Yaak ${context.source.yaakVersion})`)}`,
+		`${colors.dim("Export")}       ${context.exportPath ? rel(context.exportPath) : "(in memory)"} ${colors.dim(`(Yaak ${context.source.yaakVersion})`)}`,
 		`${colors.dim("Workspace")}    ${context.document.workspace.name} ${colors.dim(`· ${requests} requests, ${folders} folders`)}`,
 		`${colors.dim("Environment")}  ${context.document.environment?.name ?? colors.dim("none")}`,
 		`${colors.dim("Theme")}        ${context.theme.name} ${colors.dim(context.theme.packageName ?? rel(context.theme.root))}`,

package/dist/index.d.ts

@@ -1,84 +1,10 @@
-import { ResolvedConfig, ResolvedConfig as ResolvedConfig$1, YaakdocConfig, YaakdocConfig as YaakdocConfig$1, defineConfig } from "@yaakdoc/config";
-import { ThemeDefinition, ThemeDefinition as ThemeDefinition$1, defineTheme } from "@yaakdoc/react/theme";
+import { _ as themePackageCandidates, a as withBase, c as Route, f as resolveContext, g as themeFromDefinition, h as resolveTheme, i as emptyOutDir, l as YaakdocOptions, m as ThemeError, n as RenderEntry, o as writeSite, p as ResolvedTheme, r as assertSafeOutDir, s as Context, t as VERSION, u as matchRoute } from "./version-Bwv0ibuY.js";
+import { ResolvedConfig, YaakdocConfig, YaakdocConfig as YaakdocConfig$1, defineConfig } from "@yaakdoc/config";
+import { ThemeDefinition, defineTheme } from "@yaakdoc/react/theme";
 import { Snippet, defineSnippet } from "@yaakdoc/snippets";
-import { PreparedDocument, YaakDocument } from "@yaakdoc/core";
 import { Plugin, ViteDevServer } from "vite";
 import { Server } from "node:http";
-import { PageData, SiteData } from "@yaakdoc/react";
-//#region src/node/theme.d.ts
-type ResolvedTheme = {
-  name: string;
-  definition: ThemeDefinition$1;
-  /** Directory of the theme manifest. */
-  root: string;
-  manifest: string;
-  /** Absolute paths. */
-  entry: string;
-  client: string | null;
-  styles: string[];
-  /** Validated theme options. */
-  options: Record<string, unknown>;
-  /** Package name, when the theme comes from npm. */
-  packageName: string | null;
-  /** Files (importers) used as fallbacks when a theme dependency is not installed locally. */
-  fallbackImporters: string[];
-  highlight: {
-    light: string;
-    dark: string;
-  };
-};
-export declare class ThemeError extends Error {
-  name: string;
-}
-/** Candidate package names for a theme spec: `kiseki` → `@yaakdoc/theme-kiseki`, `yaakdoc-theme-kiseki`. */
-export declare function themePackageCandidates(spec: string): string[];
-/** Loads and validates a theme from a short name, package name or local path. */
-export declare function resolveTheme(spec: string, options: {
-  root: string;
-  themeOptions: Record<string, unknown>;
-}): Promise<ResolvedTheme>;
-//#endregion
-//#region src/node/context.d.ts
-type YaakdocOptions = {
-  /** Project directory (default: `process.cwd()`). */
-  cwd?: string;
-  /** Explicit config file. */
-  configFile?: string;
-  /** Config overrides (e.g. from CLI flags). Takes precedence over the config file. */
-  overrides?: YaakdocConfig$1;
-};
-type Route = {
-  /** URL path including the base, e.g. `/docs/products/`. */
-  path: string;
-  /** Output file relative to outDir, e.g. `products/index.html`. */
-  file: string;
-  page: PageData;
-};
-type Context = {
-  cwd: string;
-  root: string;
-  configFile: string | null;
-  config: ResolvedConfig$1;
-  exportPath: string;
-  source: YaakDocument;
-  theme: ResolvedTheme;
-  document: PreparedDocument;
-  site: SiteData;
-  routes: Route[];
-  notFound: Route;
-  /** Markdown/text outputs keyed by URL path (e.g. `/products.md`, `/llms.txt`). */
-  textFiles: Map<string, string>;
-  /** Local branding assets keyed by URL path → absolute file path. */
-  assets: Map<string, string>;
-  /** Files that trigger a full rebuild of the context when changed. */
-  watchFiles: string[];
-};
-export declare const VERSION: string;
-/** Loads config, export and theme, and prepares everything needed to render the site. */
-export declare function resolveContext(options?: YaakdocOptions): Promise<Context>;
-/** Finds the route for a URL path (ignoring query/hash; `/x` matches `/x/`). */
-export declare function matchRoute(context: Context, pathname: string): Route | null;
-//#endregion
+import { Assets } from "@yaakdoc/react";
 //#region src/node/build.d.ts
 type BuildResult = {
   outDir: string;
@@ -88,6 +14,20 @@ type BuildResult = {
 };
 /** Builds the static site: client assets, prerendered HTML for every route, Markdown and llms.txt. */
 export declare function build(options?: YaakdocOptions): Promise<BuildResult>;
+type ThemeBundle = {
+  /** Client assets, relative to the output directory. */
+  assets: Assets;
+  /** The SSR entry (exports `render`), in a temporary directory inside the output directory. */
+  ssrEntry: string;
+};
+/**
+ * Builds the theme with Vite: the island runtime and CSS into `outDir` (emptied first), and the SSR
+ * entry, fully bundled so it runs from anywhere. Pass `base: "./"` for client assets that work
+ * under any base path (used to precompile the theme bundled into the Yaak plugin).
+ */
+export declare function bundleTheme(context: Context, outDir: string, options?: {
+  base?: string;
+}): Promise<ThemeBundle>;
 //#endregion
 //#region src/node/dev.d.ts
 type DevServerOptions = YaakdocOptions & {
@@ -150,6 +90,7 @@ export declare function init(options?: InitOptions): Promise<{
 //#endregion
 //#region src/node/plugin.d.ts
 export declare const VIRTUAL_SERVER = "virtual:yaakdoc/entry-server";
+/** The SSR entry exports `render` (see `RenderEntry`). */
 export declare const VIRTUAL_CLIENT = "virtual:yaakdoc/entry-client";
 /**
  * The yaakdoc Vite plugin: virtual SSR/client entries, theme-scoped `@/` alias, and fallback
@@ -174,4 +115,4 @@ export declare function preview(options?: PreviewOptions): Promise<{
   close: () => Promise<void>;
 }>;
 //#endregion
-export { type BuildResult, type Context, type DevServer, type DevServerOptions, type EjectOptions, type EjectResult, type InitOptions, type PreviewOptions, type ResolvedConfig, type ResolvedTheme, type Route, type Snippet, type ThemeDefinition, type YaakdocConfig, type YaakdocOptions, defineConfig, defineSnippet, defineTheme };
+export { type BuildResult, type Context, type DevServer, type DevServerOptions, type EjectOptions, type EjectResult, type InitOptions, type PreviewOptions, type RenderEntry, type ResolvedConfig, type ResolvedTheme, type Route, type Snippet, type ThemeBundle, type ThemeDefinition, ThemeError, VERSION, type YaakdocConfig, type YaakdocOptions, assertSafeOutDir, defineConfig, defineSnippet, defineTheme, emptyOutDir, matchRoute, resolveContext, resolveTheme, themeFromDefinition, themePackageCandidates, withBase, writeSite };

package/dist/index.js

@@ -1,5 +1,6 @@
-import { a as createDevServer, c as VIRTUAL_SERVER, d as matchRoute, f as resolveContext, h as themePackageCandidates, i as schemaUrl, l as yaakdocPlugin, m as resolveTheme, n as eject, o as build, p as ThemeError, r as init, s as VIRTUAL_CLIENT, t as preview, u as VERSION } from "./preview-2YFamRKo.js";
+import { a as matchRoute, c as VERSION, d as themeFromDefinition, f as themePackageCandidates, i as writeSite, l as ThemeError, n as emptyOutDir, r as withBase, s as resolveContext, t as assertSafeOutDir, u as resolveTheme } from "./site-X7q76qYf.js";
+import { a as createDevServer, c as VIRTUAL_CLIENT, i as schemaUrl, l as VIRTUAL_SERVER, n as eject, o as build, r as init, s as bundleTheme, t as preview, u as yaakdocPlugin } from "./preview-Ba1BfVZV.js";
 import { defineConfig } from "@yaakdoc/config";
 import { defineTheme } from "@yaakdoc/react/theme";
 import { defineSnippet } from "@yaakdoc/snippets";
-export { ThemeError, VERSION, VIRTUAL_CLIENT, VIRTUAL_SERVER, build, createDevServer, defineConfig, defineSnippet, defineTheme, eject, init, matchRoute, preview, resolveContext, resolveTheme, schemaUrl, themePackageCandidates, yaakdocPlugin };
+export { ThemeError, VERSION, VIRTUAL_CLIENT, VIRTUAL_SERVER, assertSafeOutDir, build, bundleTheme, createDevServer, defineConfig, defineSnippet, defineTheme, eject, emptyOutDir, init, matchRoute, preview, resolveContext, resolveTheme, schemaUrl, themeFromDefinition, themePackageCandidates, withBase, writeSite, yaakdocPlugin };