@theholocron/astro-config 8.9.0-alpha.2 → 8.9.0-alpha.4

package/README.md

@@ -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) and `label` (default "API reference") are optional. `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,7 +1,9 @@
 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"]>;
 export interface DocsConfig {
   name: string;
   github: string;
@@ -11,10 +13,41 @@ export interface DocsConfigInput {
   docs: DocsConfig;
   starlight: typeof starlight;
   docsTheme: typeof docsTheme;
+  /** Further Starlight plugins, added after the docs theme (for example the ones `apiReference()` returns). */
+  plugins?: StarlightPlugins;
   srcDir?: string;
   outDir?: string;
   publicDir?: string;
   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>;
+export declare function defineConfig({ docs, starlight, docsTheme, plugins, srcDir, outDir, publicDir, base, site }: DocsConfigInput): ReturnType<typeof defineConfig$1>;
+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;
+}
+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 }: ApiReferenceInput): ApiReference;
 export {};

package/dist/index.js

@@ -1,8 +1,10 @@
+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 }) {
+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,7 +12,7 @@ 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",
@@ -20,4 +22,28 @@ function defineConfig({ docs, starlight, docsTheme, srcDir, outDir, publicDir, b
 		}), 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" }) {
+	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
+			}
+		})
+	};
+}
+export { apiReference, defineConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/astro-config",
-  "version": "8.9.0-alpha.2",
+  "version": "8.9.0-alpha.4",
   "description": "Astro configuration factory for theholocron docs sites.",
   "keywords": [
     "astro",
@@ -32,17 +32,20 @@
     "dist/"
   ],
   "devDependencies": {
-    "@astrojs/react": "^6.0.0",
+    "@astrojs/react": "^6.0.6",
     "@astrojs/starlight": "^0.41.7",
-    "@theholocron/docs-theme": "^1.3.5",
     "@vitest/coverage-v8": "^5.0.5",
-    "astro": "^7.2.4",
+    "astro": "^7.3.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "starlight-typedoc": "^0.23.1",
     "tsdown": "^0.23.3",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.14.1",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
-    "@theholocron/tsconfig": "8.9.0-alpha.2"
+    "@theholocron/docs-theme": "^1.10.5-alpha.1",
+    "@theholocron/tsconfig": "8.9.0-alpha.4"
   },
   "peerDependencies": {
     "@astrojs/react": ">=6.0.0",