reatom · BANOnotIT · May 9, 2025 · May 9, 2025 · May 9, 2025 · May 13, 2025
diff --git a/docs/adapters.config.ts → docs/astro.autogen.ts b/docs/adapters.config.ts → docs/astro.autogen.ts
@@ -1,8 +1,17 @@
-import { defineConfig } from './config/integrations/package-reference'
+import { defineConfig } from './config/integrations/package-reference.ts'
 
 export const adapters = await defineConfig([
   '../packages/lit/',
   '../packages/preact/',
   '../packages/react/',
   '../packages/vue/',
 ])
+
+export const packages = await defineConfig([
+  '../packages/core/'
+])
+
+export const allPackages = [
+  ...adapters,
+  ...packages,
+]
diff --git a/docs/astro.config.ts b/docs/astro.config.ts
@@ -3,8 +3,8 @@ import starlight from '@astrojs/starlight'
 import starlightLinksValidator from 'starlight-links-validator'
 import starlightLlmsTxt from 'starlight-llms-txt'
 import rehypeSlug from 'rehype-slug'
-import { sidebar } from './astro.sidebar'
-import { devServerFileWatcher } from './config/integrations/dev-server-file-watcher'
+import { sidebar } from './astro.sidebar.ts'
+import { devServerFileWatcher } from './config/integrations/dev-server-file-watcher.ts'
 
 // https://astro.build/config
 export default defineConfig({
@@ -14,7 +14,7 @@ export default defineConfig({
     devServerFileWatcher([
       './config/**', // Custom plugins and integrations
       './astro.sidebar.ts', // Sidebar configuration file
-      './adapters.config.ts', // References configuration file
+      './astro.autogen.ts', // References configuration file
     ]),
     starlight({
       sidebar,

diff --git a/docs/astro.sidebar.ts b/docs/astro.sidebar.ts
@@ -1,18 +1,15 @@
-import { group } from './config/sidebar'
-import { makeSidebar } from './config/integrations/package-reference'
+import type { StarlightIcon } from '@astrojs/starlight/types'
 
-import { adapters } from './adapters.config'
+import { group } from './config/sidebar.ts'
+import { makeSidebar } from './config/integrations/package-reference.ts'
+import { adapters, packages } from './astro.autogen.ts'
 
 export const sidebar = [
   group('Start', {
+    badge: icon('rocket'),
     items: [
       group('Essentials', {
-        items: [
-          'start/setup',
-          'start/atoms',
-          'start/actions',
-          'start/async',
-        ],
+        items: ['start/setup', 'start/atoms', 'start/actions', 'start/async'],
       }),
       group('Advanced', {
         items: [
@@ -26,6 +23,7 @@ export const sidebar = [
   }),
 
   group('Handbook', {
+    badge: icon('open-book'),
     items: [
       'handbook/history',
       'handbook/atomization',
@@ -38,12 +36,23 @@ export const sidebar = [
   }),
 
   group('Guides', {
+    badge: icon('puzzle'),
     autogenerate: {
       directory: 'guides',
     },
   }),
 
-  group('Adapters', {
-    items: await makeSidebar(adapters, { prefix: 'adapters' }),
+  group('Reference', {
+    badge: icon('information'),
+    items: [
+      ...await makeSidebar(packages, { prefix: 'package' }),
+      group('Adapters', {
+        items: await makeSidebar(adapters, { prefix: 'package' }),
+      }),
+    ],
   }),
 ]
+
+function icon(iconName: StarlightIcon) {
+  return iconName
+}
diff --git a/docs/config/integrations/package-reference.ts b/docs/config/integrations/package-reference.ts
@@ -1,18 +1,30 @@
 import type starlight from '@astrojs/starlight'
-import { resolve, join } from 'node:path'
-import { readFile } from 'node:fs/promises'
+import { defu } from 'defu'
+import { join, relative, sep as pathSep } from 'node:path'
+import { fs } from 'zx'
+import { glob, Loader } from 'astro/loaders'
 
 type StarlightSidebarConfig = NonNullable<
   Parameters<typeof starlight>[0]['sidebar']
 >
 type StarlightSidebarEntry = StarlightSidebarConfig[number]
 type StarlightSidebarLink = Extract<StarlightSidebarEntry, { link: string }>
 
+type ReferenceJSON = {
+  /** @default: "./package.json" */
+  'package.json'?: string
+  /** @default "./README.md" */
+  introduction?: string
+  referenceDocs?: string
+  changelog?: string
+}
+
 type PackageRef = {
-  path: string
-  package: { name: string }
+  absolutePath: string
+  packageJson: { name: string }
   slug: string
-  originalSelector: string
+  relativePath: string
+  referenceJson: ReferenceJSON
 }
 
 export function nameToSlug(name: string): string {
@@ -21,16 +33,26 @@ export function nameToSlug(name: string): string {
 
 export async function defineConfig(paths: string[]): Promise<PackageRef[]> {
   return Promise.all(
-    paths.map(async (pkgPath) => {
-      const path = resolve(process.cwd(), pkgPath)
-      const pkgBody = await readFile(join(path, 'package.json'), 'utf8')
-      const pkgJson = JSON.parse(pkgBody)
-      const npmName = pkgJson.name as string
+    paths.map(async (relativePath) => {
+      const absolutePath = join(process.cwd(), relativePath)
+      const referencePath = join(absolutePath, 'reference.json')
+      const referenceBody = await fs.readJson(referencePath).catch(() => ({}))
+      const referenceJson = defu(referenceBody, {
+        'package.json': './package.json',
+        introduction: './README.md',
+      }) as ReferenceJSON
+
+      const packageJsonPath = join(absolutePath, referenceJson['package.json'])
+      const packageJson = (await fs.readJson(packageJsonPath)) as {
+        name: string
+      }
+
       return {
-        path,
-        package: { name: npmName },
-        slug: nameToSlug(npmName),
-        originalSelector: pkgPath,
+        absolutePath,
+        packageJson,
+        slug: nameToSlug(packageJson.name),
+        relativePath: relativePath,
+        referenceJson,
       }
     }),
   )
@@ -40,10 +62,90 @@ export function makeSidebar(
   packages: PackageRef[],
   { prefix }: { prefix?: string },
 ): Promise<StarlightSidebarLink[]> {
-  const links = packages.map(async (pkg) => ({
-    label: pkg.package.name,
-    link: `/${prefix ? prefix + '/' : ''}${pkg.slug}`,
-  }))
+  const links = packages.map(async (pkg) => {
+    const packageLink = `/${prefix ? prefix + '/' : ''}${pkg.slug}`
+
+    const pages = []
+    if (pkg.referenceJson.referenceDocs) {
+      pages.push({
+        label: 'Reference',
+        link: `${packageLink}/reference`,
+      })
+    }
+    if (pkg.referenceJson.changelog) {
+      pages.push({
+        label: 'Changelog',
+        link: `${packageLink}/changelog`,
+      })
+    }
+
+    return pages.length
+      ? {
+          label: pkg.packageJson.name,
+          collapsed: true,
+          items: [
+            {
+              label: 'Introduction',
+              link: packageLink,
+            },
+            ...pages,
+          ],
+        }
+      : {
+          label: pkg.packageJson.name,
+          link: packageLink,
+        }
+  })
 
   return Promise.all(links)
 }
+
+export function loader(pkgs: PackageRef[]): Loader {
+  const base = pkgs
+    .map((pkg) => pkg.absolutePath)
+    .reduce((base, candidate) => {
+      if (candidate.startsWith(base)) return base
+
+      let candidateParts = candidate.split(pathSep)
+      let baseParts = base.split(pathSep)
+      const minLength = Math.min(candidateParts.length, baseParts.length)
+      let i = 0
+      for (; i < minLength; i++) {
+        if (baseParts[i] !== candidateParts[i]) {
+          break
+        }
+      }
+      return baseParts.slice(0, i).join(pathSep)
+    })
+
+  let map = new Map<string, string>()
+  let pattern: string[] = []
+
+  function trackFile(pkg: PackageRef, prop: keyof ReferenceJSON) {
+    const localTarget = pkg.referenceJson[prop]
+    if (localTarget) {
+      // resolve absolute path in FS
+      const absolutePath = join(pkg.absolutePath, localTarget)
+      // get path relative to `base`, it'll be used below in generateId
+      const relativePath = relative(base, absolutePath)
+      pattern.push(relativePath)
+      map.set(relativePath, `${pkg.slug}:${prop}`)
+    }
+  }
+
+  for (const pkg of pkgs) {
+    trackFile(pkg, 'introduction')
+    trackFile(pkg, 'referenceDocs')
+    trackFile(pkg, 'changelog')
+  }
+
+  return glob({
+    pattern,
+    base,
+    generateId({ entry, base }) {
+      const id = map.get(entry)
+      if (!id) throw new Error(`Not found id for ${entry} on ${base}`)
+      return id
+    },
+  })
+}
diff --git a/docs/package-lock.json b/docs/package-lock.json
diff --git a/docs/package.json b/docs/package.json
@@ -14,6 +14,7 @@
   "dependencies": {
     "@astrojs/starlight": "^0.34.0",
     "astro": "^5.6.1",
+    "defu": "^6.1.4",
     "fast-glob": "^3.3.3",
     "mermaid": "^11.6.0",
     "rehype-autolink-headings": "^7.1.0",

diff --git a/docs/src/components/starlight/Sidebar.astro b/docs/src/components/starlight/Sidebar.astro
@@ -43,12 +43,6 @@ assertGroups(sidebar);
 // The id is prefixed to avoid clashing with existing heading IDs on the page.
 const makeId = (label: string) => '__tab-' + label.toLowerCase().replaceAll(/\s+/g, '-');
 
-
-
-/** Get the icon for a group. Update the icon names in the array to change the icons associated with a group. */
-const getIcon = (index: number) =>
-	(['rocket', 'open-book', 'information'] as const)[index];
-
 /** Determine if an array of sidebar items contains the current page.  */
 const isCurrent = (sidebar: SidebarEntry[]): boolean =>
 	sidebar
@@ -60,9 +54,9 @@ const isCurrent = (sidebar: SidebarEntry[]): boolean =>
 	<TabbedContent class="tabbed-sidebar" styled={false}>
 		<Fragment slot="tab-list">
 			{
-				sidebar.map(({ label, entries }, index) => (
+				sidebar.map(({ label, entries, badge }) => (
 					<TabListItem id={makeId(label)} initial={isCurrent(entries)} class="tab-item">
-						<Icon class="icon" name={getIcon(index)} /> {label}
+						<Icon class="icon" name={badge?.text} /> {label}
 					</TabListItem>
 				))
 			}

diff --git a/docs/src/content.config.ts b/docs/src/content.config.ts
@@ -1,14 +1,10 @@
 import { defineCollection } from 'astro:content'
 import { docsSchema } from '@astrojs/starlight/schema'
 import { docsLoader } from '@astrojs/starlight/loaders'
-import { glob } from 'astro/loaders'
+import { allPackages } from '../astro.autogen.js'
+import { loader } from '../config/integrations/package-reference.js'
 
 export const collections = {
   docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
-  readmes: defineCollection({
-    loader: glob({
-      pattern: '*/README.md',
-      base: '../packages',
-    }),
-  }),
+  packages: defineCollection({ loader: loader(allPackages) }),
 }
diff --git a/docs/src/content.ts b/docs/src/content.ts
@@ -1,5 +1,7 @@
-import { getCollection } from 'astro:content';
+import { getCollection } from 'astro:content'
 
-export const docsPages = await getCollection('docs');
-export const readmesPages = await getCollection('readmes')
-export const allPages = [...docsPages, ...readmesPages]
+export const docsPages = await getCollection('docs')
+export const packagesPages = await getCollection('packages')
+export const allPages = [...docsPages, ...packagesPages]
+
+console.log(packagesPages.map((a) => a.id))
diff --git a/docs/src/pages/adapters/[slug].astro b/docs/src/pages/adapters/[slug].astro
diff --git a/docs/src/pages/package/[slug].astro b/docs/src/pages/package/[slug].astro
@@ -0,0 +1,26 @@
+---
+import type { GetStaticPaths } from 'astro'
+import { packagesPages } from '../../content'
+import { render } from 'astro:content'
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro'
+import { allPackages } from '../../../astro.autogen.ts'
+import { joinBy } from '../../util/join.ts'
+
+export const getStaticPaths = (() => {
+  return joinBy(allPackages, packagesPages, (ref, page) =>
+    page.id === ref.slug + ':introduction',
+  ).map(([ref, page]) => ({
+    props: { page, ref },
+    params: { slug: ref.slug },
+  }))
+}) satisfies GetStaticPaths
+
+const { page, ref } = Astro.props
+
+const { Content, headings } = await render(page)
+---
+
+<StarlightPage frontmatter={{ title: ref.packageJson.name }} headings={headings} >
+
+  <Content />
+</StarlightPage>