@theholocron/astro-config 8.9.0-alpha.1 → 8.9.0-alpha.15

package/README.md

@@ -1,6 +1,6 @@
 # Astro Config
 
-An [Astro configuration](https://docs.astro.build/en/reference/configuration-reference/) factory for theholocron docs sites.
+An [Astro configuration](https://docs.astro.build/en/reference/configuration-reference/) factory for the theholocron docs sites.
 
 ## Installation
 
@@ -61,9 +61,37 @@ export default defineConfig({
 });
 ```
 
+### API reference from TSDoc
+
+`apiReference()` generates a package's API reference from its TSDoc comments each time the docs are built or served (nothing generated is committed). It returns a Starlight plugin and a sidebar group:
+
+```ts
+import { apiReference, defineConfig } from "@theholocron/astro-config";
+import { createStarlightTypeDocPlugin } from "starlight-typedoc";
+
+const arrayUtils = apiReference({
+  createPlugin: createStarlightTypeDocPlugin,
+  root: new URL("./", import.meta.url),
+  package: "utils/array-utils",
+});
+
+export default defineConfig({
+  docs: {
+    name: "Utils",
+    github: "utils",
+    sidebar: [{ label: "array-utils", items: [{ label: "Overview", slug: "array-utils" }, arrayUtils.group] }],
+  },
+  plugins: [arrayUtils.plugin],
+  starlight,
+  docsTheme,
+});
+```
+
+`entryPoints` (default `["src/index.ts"]`, relative to the package), `label` (default "API reference") and `skipErrorChecking` (default `false`) are optional. Set `skipErrorChecking` for a package whose types come from sources TypeDoc cannot type-check on its own, such as this one's from Starlight; TypeDoc then does not stop the build on type errors. `starlight-typedoc` ships TypeScript source, so, like `starlight` and `docsTheme`, you import it in your own config and pass it in; install `starlight-typedoc`, `typedoc` and `typedoc-plugin-markdown` in the site.
+
 ## What it generates
 
-- `site` — `https://theholocron.github.io`
+- `site` — only when you pass it (for example `https://docs.theholocron.dev`); without it Starlight cannot generate a sitemap
 - `base` — `/${docs.slug}`
 - Starlight integration with the `@theholocron/docs-theme` plugin
 - GitHub social link to `https://github.com/theholocron/${docs.slug}`

package/dist/index.d.ts

@@ -1,20 +1,80 @@
 import { defineConfig as defineConfig$1 } from "astro/config";
 import starlight from "@astrojs/starlight";
 import { docsTheme } from "@theholocron/docs-theme";
+import { createStarlightTypeDocPlugin } from "starlight-typedoc";
 type StarlightSidebar = NonNullable<Parameters<typeof starlight>[0]["sidebar"]>;
+type StarlightPlugins = NonNullable<Parameters<typeof starlight>[0]["plugins"]>;
+/**
+ * The GitHub org a site's repo belongs to when `docs.org` is not given. This package is published with no dependency on
+ * the CLI and runs without a `holocron.config`, so it keeps its own one named default instead of a repeated literal.
+ */
+export declare const DEFAULT_ORG = "theholocron";
+/** The docs site's identity: its title, its GitHub repo name and its sidebar. */
 export interface DocsConfig {
+  /** The site title Starlight shows (passed as Starlight's `title`). */
   name: string;
+  /** The repo name under the GitHub org; builds the social link and the default `base` (`/<github>`). */
   github: string;
+  /** The GitHub org that owns the repo. Defaults to {@link DEFAULT_ORG}. */
+  org?: string;
+  /** The Starlight sidebar definition, passed to Starlight unchanged. */
   sidebar: StarlightSidebar;
 }
+/** Everything `defineConfig` needs to build the Astro config for a Starlight docs site. */
 export interface DocsConfigInput {
+  /** The docs site's name, repo and sidebar. */
   docs: DocsConfig;
+  /** The `starlight` integration, imported by the site's own config so Astro's loader handles it. */
   starlight: typeof starlight;
+  /** The `docsTheme` Starlight plugin from `@theholocron/docs-theme`, imported by the site's own config. */
   docsTheme: typeof docsTheme;
+  /** Further Starlight plugins, added after the docs theme (for example the ones `apiReference()` returns). */
+  plugins?: StarlightPlugins;
+  /** Astro's `srcDir`. Omitted from the config when unset, so Astro's default (`./src`) applies. */
   srcDir?: string;
+  /** Astro's `outDir`, the build output folder. Omitted from the config when unset, so Astro's default applies. */
   outDir?: string;
+  /** Astro's `publicDir`, the folder of static assets. Omitted from the config when unset, so Astro's default applies. */
   publicDir?: string;
+  /** Astro's `base`, the path the site is served under. Defaults to `/<docs.github>`. */
   base?: string;
+  /** The site's absolute origin (for example `https://docs.theholocron.dev`). Starlight needs it to generate a sitemap. */
+  site?: string;
 }
-export declare function defineConfig({ docs, starlight, docsTheme, srcDir, outDir, publicDir, base }: DocsConfigInput): ReturnType<typeof defineConfig$1>;
+/** Builds the Astro config for a Starlight docs site: the docs theme, a GitHub social link, the React integration and an `@` alias to the docs source folder. */
+export declare function defineConfig({ docs, starlight, docsTheme, plugins, srcDir, outDir, publicDir, base, site }: DocsConfigInput): ReturnType<typeof defineConfig$1>;
+/** Options for `apiReference`. */
+export interface ApiReferenceInput {
+  /** `createStarlightTypeDocPlugin` from your own `starlight-typedoc` import, as with `starlight` and `docsTheme`. */
+  createPlugin: typeof createStarlightTypeDocPlugin;
+  /** The repo root, as a URL or path: `new URL("./", import.meta.url)` from a config at the root. */
+  root: URL | string;
+  /** The package's folder from the repo root (`utils/array-utils`). */
+  package: string;
+  /** Entry points, relative to the package. Defaults to `src/index.ts`. */
+  entryPoints?: string[];
+  /** The sidebar group's label. Defaults to "API reference". */
+  label?: string;
+  /**
+   * Tell TypeDoc not to stop on type errors. For a package whose types come from sources TypeDoc cannot check on its
+   * own (this package's, from Starlight); the build would otherwise fail on them. Defaults to `false`.
+   */
+  skipErrorChecking?: boolean;
+}
+/** What `apiReference` returns: the Starlight plugin and the sidebar group that belong together. */
+export interface ApiReference {
+  /** Add to `defineConfig({ plugins })`. */
+  plugin: StarlightPlugins[number];
+  /** Put in the sidebar where the reference should appear. */
+  group: StarlightSidebar[number];
+}
+/**
+ * The generated API reference of one package: its TSDoc comments, run through TypeDoc each time the docs are built
+ * or served, as pages under `<package>/api` and a collapsed sidebar group. Nothing generated is committed.
+ *
+ * `starlight-typedoc` ships TypeScript source, so, like `starlight` and `docsTheme`, it is imported by the site's
+ * own config and passed in, which keeps Astro's loader in charge of it. Install `starlight-typedoc`, `typedoc` and
+ * `typedoc-plugin-markdown` in the site.
+ */
+export declare function apiReference({ createPlugin, root, package: dir, entryPoints, label, skipErrorChecking }: ApiReferenceInput): ApiReference;
 export {};

package/dist/index.js

@@ -1,8 +1,16 @@
+import { fileURLToPath } from "node:url";
 import react from "@astrojs/react";
 import { defineConfig as defineConfig$1 } from "astro/config";
 // index.ts
-function defineConfig({ docs, starlight, docsTheme, srcDir, outDir, publicDir, base }) {
+/**
+* The GitHub org a site's repo belongs to when `docs.org` is not given. This package is published with no dependency on
+* the CLI and runs without a `holocron.config`, so it keeps its own one named default instead of a repeated literal.
+*/
+const DEFAULT_ORG = "theholocron";
+/** Builds the Astro config for a Starlight docs site: the docs theme, a GitHub social link, the React integration and an `@` alias to the docs source folder. */
+function defineConfig({ docs, starlight, docsTheme, plugins, srcDir, outDir, publicDir, base, site }) {
 	return defineConfig$1({
+		...site && { site },
 		base: base ?? `/${docs.github}`,
 		...srcDir && { srcDir },
 		...outDir && { outDir },
@@ -10,14 +18,39 @@ function defineConfig({ docs, starlight, docsTheme, srcDir, outDir, publicDir, b
 		vite: { resolve: { alias: { "@": new URL(srcDir ?? "src", `file://${process.cwd()}/`).pathname } } },
 		integrations: [starlight({
 			title: docs.name,
-			plugins: [docsTheme()],
+			plugins: [docsTheme(), ...plugins ?? []],
 			social: [{
 				icon: "github",
 				label: "GitHub",
-				href: `https://github.com/theholocron/${docs.github}`
+				href: `https://github.com/${docs.org ?? "theholocron"}/${docs.github}`
 			}],
 			sidebar: docs.sidebar
 		}), react()]
 	});
 }
-export { defineConfig };
+/**
+* The generated API reference of one package: its TSDoc comments, run through TypeDoc each time the docs are built
+* or served, as pages under `<package>/api` and a collapsed sidebar group. Nothing generated is committed.
+*
+* `starlight-typedoc` ships TypeScript source, so, like `starlight` and `docsTheme`, it is imported by the site's
+* own config and passed in, which keeps Astro's loader in charge of it. Install `starlight-typedoc`, `typedoc` and
+* `typedoc-plugin-markdown` in the site.
+*/
+function apiReference({ createPlugin, root, package: dir, entryPoints = ["src/index.ts"], label = "API reference", skipErrorChecking = false }) {
+	const [plugin, group] = createPlugin();
+	const inPackage = (path) => fileURLToPath(new URL(`${dir}/${path}`, root));
+	return {
+		group,
+		plugin: plugin({
+			entryPoints: entryPoints.map(inPackage),
+			tsconfig: inPackage("tsconfig.json"),
+			output: `${dir}/api`,
+			sidebar: {
+				label,
+				collapsed: true
+			},
+			...skipErrorChecking ? { typeDoc: { skipErrorChecking: true } } : {}
+		})
+	};
+}
+export { DEFAULT_ORG, apiReference, defineConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/astro-config",
-  "version": "8.9.0-alpha.1",
+  "version": "8.9.0-alpha.15",
   "description": "Astro configuration factory for theholocron docs sites.",
   "keywords": [
     "astro",
@@ -32,17 +32,20 @@
     "dist/"
   ],
   "devDependencies": {
-    "@astrojs/react": "^6.0.0",
-    "@astrojs/starlight": "^0.41.7",
-    "@theholocron/docs-theme": "^1.3.5",
-    "@vitest/coverage-v8": "^5.0.5",
-    "astro": "^7.2.4",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "tsdown": "^0.23.3",
+    "@astrojs/react": "^7.1.2",
+    "@astrojs/starlight": "^0.42.9",
+    "@vitest/coverage-v8": "^5.1.0",
+    "astro": "^7.4.5",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "starlight-typedoc": "^0.23.2",
+    "tsdown": "^0.23.5",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.14.1",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.5",
-    "@theholocron/tsconfig": "8.9.0-alpha.1"
+    "vitest": "^5.1.0",
+    "@theholocron/docs-theme": "^1.11.0-alpha.2",
+    "@theholocron/tsconfig": "8.9.0-alpha.15"
   },
   "peerDependencies": {
     "@astrojs/react": ">=6.0.0",
@@ -57,10 +60,10 @@
     "access": "public"
   },
   "scripts": {
-    "delivery.build": "tsdown",
-    "sourceQuality.staticAnalysis": "eslint .",
+    "build": "tsdown",
+    "lint:code": "eslint .",
+    "test:unit": "vitest run --coverage",
     "test:watch": "vitest",
-    "verification.typeSafety": "tsc --noEmit",
-    "verification.unitTests": "vitest run"
+    "typecheck": "tsc --noEmit"
   }
 }