npm - lectio-docs - Versions diffs - 0.1.0 - Mend

lectio-docs 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/LICENSE +21 -0
package/app/components/site-header.tsx +149 -0
package/app/content.server.ts +49 -0
package/app/root.tsx +52 -0
package/app/routes/docs.css +92 -0
package/app/routes/docs.tsx +166 -0
package/app/routes.ts +29 -0
package/app/site.config.ts +8 -0
package/bin/lectio.mjs +176 -0
package/package.json +42 -0
package/react-router.config.ts +32 -0
package/vite.config.ts +6 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Losol AS
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/app/components/site-header.tsx ADDED Viewed

@@ -0,0 +1,149 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Link, useLocation, useMatches, useNavigate } from 'react-router';
+import { OramaProvider } from '@eventuras/lectio-docs/search';
+import { Search } from '@eventuras/lectio-docs-react';
+import { Navbar } from '@eventuras/ratio-ui/core/Navbar';
+import { NavTree } from '@eventuras/ratio-ui/core/NavTree';
+import { ThemeToggle } from '@eventuras/ratio-ui/core/ThemeToggle';
+import type { DocsNavGroup } from '../routes/docs';
+import { site } from '../site.config';
+/**
+ * Site header on ratio-ui's Navbar (sticky app-header form: fluid + elevated —
+ * elevation, never borders). The search zone hosts the lectio <Search>
+ * CommandPalette, which brings its own trigger and the global ⌘K shortcut.
+ *
+ * On narrow screens the docs nav collapses into the navbar's own
+ * Toggle/Collapse pair (the "pocket library" pattern): a burger that folds the
+ * NavTree out under the bar. The nav data comes from the docs route's loader
+ * via useMatches, so the header stays route-agnostic. The Navbar is keyed on
+ * the pathname because the disclosure state is internal with no controlled
+ * API — remounting on navigation is what closes the panel after a link is
+ * followed.
+ *
+ * Theme state lives on <html data-theme> (set before first paint by the
+ * blocking script in root.tsx). The toggle reads it after mount — `null`
+ * during SSR keeps server and client renders identical — and persists the
+ * choice so the init script can restore it next visit.
+ */
+export function SiteHeader() {
+  const navigate = useNavigate();
+  const { pathname } = useLocation();
+  const [theme, setTheme] = useState<'light' | 'dark' | null>(null);
+  // The index is built from the collected manifest at build time and shipped
+  // as a static asset; Orama restores it in the browser on the first query.
+  const provider = useMemo(() => new OramaProvider('/search-index.json'), []);
+  // Nav tree from whichever active route provided it (the docs loader).
+  // UIMatch carries the loader's return as `loaderData` in React Router v8.
+  const matches = useMatches();
+  const docsData = matches.find(
+    (m) => m.loaderData && typeof m.loaderData === 'object' && 'navGroups' in m.loaderData,
+  )?.loaderData as { navGroups: DocsNavGroup[]; slug: string } | undefined;
+  useEffect(() => {
+    const current = document.documentElement.getAttribute('data-theme');
+    setTheme(current === 'dark' ? 'dark' : 'light');
+  }, []);
+  const onThemeChange = (next: 'light' | 'dark') => {
+    document.documentElement.setAttribute('data-theme', next);
+    try {
+      localStorage.setItem('lectio-theme', next);
+    } catch {
+      // Storage disabled (private mode) — the toggle still works for this
+      // visit, the choice just isn't remembered. Mirrors the init script's
+      // guarded read.
+    }
+    setTheme(next);
+  };
+  return (
+    <Navbar key={pathname} sticky elevated fluid>
+      <Navbar.Brand>
+        <Link
+          to="/"
+          style={{ display: 'flex', alignItems: 'center', gap: 10, textDecoration: 'none', color: 'var(--text)' }}
+        >
+          <span
+            aria-hidden
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              width: 32,
+              height: 32,
+              borderRadius: 9,
+              background: 'var(--color-primary-700)',
+              color: '#fff',
+            }}
+          >
+            <svg width="19" height="19" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round" strokeLinejoin="round">
+              <path d="M2 3h6a4 4 0 0 1 4 4v14a3 3 0 0 0-3-3H2z" />
+              <path d="M22 3h-6a4 4 0 0 0-4 4v14a3 3 0 0 1 3-3h7z" />
+            </svg>
+          </span>
+          <span style={{ fontFamily: 'var(--font-serif)', fontSize: 20, fontWeight: 700, letterSpacing: '-0.02em' }}>
+            {site.title}
+          </span>
+        </Link>
+      </Navbar.Brand>
+      <Navbar.Search>
+        {/* CommandPalette renders its own trigger and registers global ⌘K —
+            search is available from every page, no /search route. */}
+        <Search
+          provider={provider}
+          placeholder="Search the docs…"
+          onNavigate={(url) => navigate(url)}
+        />
+      </Navbar.Search>
+      <Navbar.Spacer />
+      <Navbar.Actions>
+        <ThemeToggle theme={theme} onThemeChange={onThemeChange} ariaLabel="Switch theme" />
+        {site.githubUrl && (
+          <a
+            href={site.githubUrl}
+            style={{ display: 'inline-flex', alignItems: 'center', gap: 7, fontSize: 14, color: 'var(--text-muted)', textDecoration: 'none' }}
+          >
+            <svg width="17" height="17" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 .5 5 .5 5 .5c-.3 1.15-.3 2.35 0 3.5A5.4 5.4 0 0 0 4 7.5c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4" />
+              <path d="M9 18c-4.51 2-5-2-7-2" />
+            </svg>
+            GitHub
+          </a>
+        )}
+        {docsData && (
+          /* Wrapper owns responsive visibility (display: none / contents in
+             docs.css) so we never fight the component's own display classes. */
+          <span className="site-nav-toggle">
+            <Navbar.Toggle controls="docs-nav" ariaLabel="Documentation menu" />
+          </span>
+        )}
+      </Navbar.Actions>
+      {docsData && (
+        <div className="site-nav-collapse">
+          <Navbar.Collapse id="docs-nav">
+            <NavTree
+              groups={docsData.navGroups}
+              currentPath={docsData.slug}
+              LinkComponent={NavCollapseLink}
+              aria-label="Documentation"
+            />
+          </Navbar.Collapse>
+        </div>
+      )}
+    </Navbar>
+  );
+}
+/** React Router adapter for NavTree — forwards active/indent/aria props. */
+function NavCollapseLink({ href, ...rest }: { href: string; children: React.ReactNode }) {
+  return <Link to={href} {...rest} />;
+}

package/app/content.server.ts ADDED Viewed

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import {
+  createContentSource,
+  type ContentSource,
+  type Manifest,
+} from '@eventuras/lectio-docs/content';
+// Absolute path to the collected content (manifest.json + markdown), from the
+// generated lectio.config.json. Written next to the app before every build —
+// by this app's collect script here, by the lectio CLI when it materializes
+// this app elsewhere — so this module is generic. Located via cwd, which the
+// build always runs in.
+const { contentDir } = JSON.parse(
+  readFileSync(join(process.cwd(), 'lectio.config.json'), 'utf-8'),
+) as { contentDir: string };
+const root = resolve(contentDir);
+let cached: ContentSource | null = null;
+/**
+ * Build the content source from the collected manifest, loading bodies from disk.
+ *
+ * `fs` is the right seam for this host: prerendering runs loaders in Node at
+ * build time, so the static output needs no server.
+ */
+export function getContentSource(): ContentSource {
+  if (cached) return cached;
+  const manifest = JSON.parse(
+    readFileSync(join(root, 'manifest.json'), 'utf-8'),
+  ) as Manifest;
+  cached = createContentSource({
+    manifest,
+    loadBody: (page) => {
+      // Resolve and enforce a separator boundary so a page.file can't escape
+      // contentDir via `..` or a prefix like `${contentDir}2/…`.
+      const filePath = resolve(root, page.file);
+      if (filePath !== root && !filePath.startsWith(root + sep)) {
+        throw new Error(`Refusing to read outside the content directory: ${page.file}`);
+      }
+      return readFileSync(filePath, 'utf-8');
+    },
+  });
+  return cached;
+}

package/app/root.tsx ADDED Viewed

@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react';
+import { Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router';
+// Design tokens + component styles for ratio-ui, which @eventuras/markdown
+// renders the collected markdown with.
+//
+// `?url` + the links export, not a side-effect import: React Router renders
+// the whole <html> document, so the stylesheet must be a real <link> in the
+// SSR head rather than something Vite injects after hydration.
+import ratioUiStylesheet from '@eventuras/ratio-ui/ratio-ui.css?url';
+import { SiteHeader } from './components/site-header';
+export function links() {
+  return [{ rel: 'stylesheet', href: ratioUiStylesheet }];
+}
+// Resolve the theme before first paint so a stored dark-mode choice (the
+// header's ThemeToggle writes it) or the system preference paints correctly
+// from the first frame — an effect after hydration would flash light first.
+// Since ratio-ui 2.15 this is purely about avoiding that flash: the page is
+// visible by default and the old hide-until-themed gate is opt-in
+// (`data-theme-loading`), which we don't need with a blocking script.
+const themeInit = `document.documentElement.setAttribute('data-theme', (function () { try { var t = localStorage.getItem('lectio-theme'); if (t === 'light' || t === 'dark') return t; } catch (e) {} return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'; })());`;
+export function Layout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <script dangerouslySetInnerHTML={{ __html: themeInit }} />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        {children}
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+export default function App() {
+  return (
+    <>
+      <SiteHeader />
+      <Outlet />
+    </>
+  );
+}

package/app/routes/docs.css ADDED Viewed

@@ -0,0 +1,92 @@
+/*
+ * Structural layout for the docs pages. Lives in CSS rather than inline
+ * styles for one reason: the responsive behavior needs media queries.
+ *
+ * Three columns on wide screens; the TOC drops first, then the sidebar
+ * collapses into the site header's Navbar.Toggle/Collapse pair (see
+ * site-header.tsx and the .site-nav-* rules below).
+ */
+.docs-shell {
+  display: flex;
+  align-items: flex-start;
+  max-width: 1400px;
+  margin: 0 auto;
+  width: 100%;
+  font-family: var(--font-body);
+  color: var(--text);
+}
+.docs-sidebar {
+  position: sticky;
+  top: 60px;
+  flex-shrink: 0;
+  width: 262px;
+  max-height: calc(100vh - 60px);
+  overflow-y: auto;
+  padding: 26px 16px 40px 24px;
+  border-right: 1px solid var(--border-1);
+}
+.docs-content-wrap {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  align-items: flex-start;
+  gap: 40px;
+  max-width: 1040px;
+  margin: 0 auto;
+  padding: 40px 40px 80px;
+}
+.docs-main {
+  flex: 1;
+  /* Lets the column actually shrink — without it, wide content (code blocks)
+     pushes the flex row apart and under the TOC column. */
+  min-width: 0;
+}
+/* The TOC owns a real, non-shrinking column — it never sits over the text. */
+.docs-toc {
+  flex-shrink: 0;
+  width: 190px;
+  position: sticky;
+  top: 86px;
+  align-self: flex-start;
+}
+/*
+ * Mobile nav lives in the site header as a Navbar.Toggle/Collapse pair (the
+ * "pocket library" pattern). These wrappers own the responsive visibility so
+ * we never fight the components' own display classes: display none/contents
+ * on a wrapper hides or reveals the child regardless of what it renders.
+ * Breakpoints are ours, aligned with the sidebar's — the components ship no
+ * visibility of their own (the "typically md:hidden" in their docs is advice
+ * to the consumer, not behavior).
+ */
+.site-nav-toggle,
+.site-nav-collapse {
+  display: none;
+}
+@media (max-width: 1100px) {
+  /* "On this page" earns its keep on wide screens only. */
+  .docs-toc {
+    display: none;
+  }
+}
+@media (max-width: 900px) {
+  .docs-sidebar {
+    display: none;
+  }
+  .site-nav-toggle,
+  .site-nav-collapse {
+    display: contents;
+  }
+  .docs-content-wrap {
+    padding: 20px 16px 60px;
+  }
+}

package/app/routes/docs.tsx ADDED Viewed

@@ -0,0 +1,166 @@
+import { useMemo } from 'react';
+import { Link, useLoaderData } from 'react-router';
+import type { TreeNode } from '@eventuras/lectio-docs/content';
+import { MarkdownContent, extractHeadings, type MarkdownComponents } from '@eventuras/markdown';
+import { Heading } from '@eventuras/ratio-ui/core/Heading';
+import { NavTree } from '@eventuras/ratio-ui/core/NavTree';
+import { TableOfContents } from '@eventuras/ratio-ui/core/TableOfContents';
+import { getTextContent, slugify } from '@eventuras/ratio-ui/utils';
+import { getContentSource } from '../content.server';
+import docsStylesheet from './docs.css?url';
+export function links() {
+  return [{ rel: 'stylesheet', href: docsStylesheet }];
+}
+export async function loader({ params }: { params: Record<string, string | undefined> }) {
+  const source = getContentSource();
+  // Docs are served at the site root, so manifest slugs map 1:1 onto URLs.
+  const rest = (params['*'] ?? '').replace(/\/$/, '');
+  const slug = rest ? `/${rest}` : '/';
+  const page = await source.getPage(slug);
+  if (!page) throw new Response(`No document for "${slug}"`, { status: 404 });
+  // navGroups is computed here (plain, serializable data) rather than in the
+  // component so the site header can pick it up via useMatches and render the
+  // same tree in its mobile Navbar.Collapse.
+  return { page, navGroups: toNavGroups(source.getTree()), slug };
+}
+/**
+ * Serializable shape of the nav tree — a plain-strings subset of ratio-ui's
+ * NavTreeGroup (whose `title: ReactNode` doesn't survive React Router's
+ * loader-serialization typing). Structurally assignable to what NavTree takes,
+ * and shared with the site header, which reads it back via useMatches.
+ */
+export interface DocsNavItem {
+  title: string;
+  href?: string;
+  id?: string;
+  children?: DocsNavItem[];
+}
+export interface DocsNavGroup {
+  label?: string;
+  items: DocsNavItem[];
+}
+/**
+ * Content tree → NavTree groups: root-level pages form the first (unlabelled)
+ * group, and each bare section becomes its own group with its title as the
+ * uppercase eyebrow — the grouped-sidebar look from the design sketch, derived
+ * from the manifest rather than hand-maintained.
+ */
+function toNavGroups(tree: TreeNode[]): DocsNavGroup[] {
+  const toItem = (node: TreeNode): DocsNavItem => ({
+    title: node.title,
+    ...(node.slug ? { href: node.slug } : { id: node.title }),
+    ...(node.children.length > 0 ? { children: node.children.map(toItem) } : {}),
+  });
+  const rootPages = tree.filter((n) => n.children.length === 0);
+  const sections = tree.filter((n) => n.children.length > 0);
+  return [
+    { items: rootPages.map(toItem) },
+    ...sections.map((section) => ({
+      label: section.title,
+      items: [
+        // A section that is itself a page keeps a link to it at the top.
+        ...(section.slug ? [{ title: 'Overview', href: section.slug }] : []),
+        ...section.children.map(toItem),
+      ],
+    })),
+  ];
+}
+/** React Router adapter for NavTree — forwards active/indent/aria props. */
+function NavLink({ href, ...rest }: { href: string; children: React.ReactNode }) {
+  return <Link to={href} {...rest} />;
+}
+export default function DocsPage() {
+  const { page, navGroups, slug } = useLoaderData<typeof loader>();
+  const headings = useMemo(() => extractHeadings(page.body), [page.body]);
+  // The only override left: anchor ids on h2/h3, slugged with ratio-ui's own
+  // slugify — the same function extractHeadings uses for the TOC, so scroll-spy
+  // and anchors can't drift. Everything else (code blocks, inline code,
+  // blockquotes, dividers) renders theme-aware upstream since markdown 0.13.
+  const markdownComponents: MarkdownComponents = useMemo(
+    () => ({
+      h2: ({ children }) => (
+        <Heading as="h2" id={slugify(getTextContent(children))} style={{ scrollMarginTop: 76 }}>
+          {children}
+        </Heading>
+      ),
+      h3: ({ children }) => (
+        <Heading as="h3" id={slugify(getTextContent(children))} style={{ scrollMarginTop: 76 }}>
+          {children}
+        </Heading>
+      ),
+    }),
+    [],
+  );
+  return (
+    <div className="docs-shell">
+      <aside className="docs-sidebar">
+        <NavTree groups={navGroups} currentPath={slug} LinkComponent={NavLink} aria-label="Documentation" />
+      </aside>
+      <div className="docs-content-wrap">
+        <main className="docs-main">
+          <MarkdownContent
+            markdown={page.body}
+            allowExternalLinks
+            customComponents={markdownComponents}
+          />
+          <footer
+            style={{
+              display: 'flex',
+              justifyContent: 'space-between',
+              alignItems: 'center',
+              marginTop: 48,
+              paddingTop: 20,
+              borderTop: '1px solid var(--border-1)',
+              fontSize: 14,
+              color: 'var(--text-subtle)',
+            }}
+          >
+            <span>
+              collected from <code>{page.source}</code>
+            </span>
+            {/* The edit link is provenance from the manifest (collect() resolves
+                the configured editUrl template per page) — the site knows
+                nothing about which repo the content came from. */}
+            {page.editUrl && (
+              <a
+                href={page.editUrl}
+                style={{ display: 'inline-flex', alignItems: 'center', gap: 6, textDecoration: 'none', color: 'var(--primary)' }}
+              >
+                Edit this page
+                <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                  <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" />
+                  <path d="M15 3h6v6" />
+                  <path d="M10 14 21 3" />
+                </svg>
+              </a>
+            )}
+          </footer>
+        </main>
+        {headings.length > 0 && (
+          <aside className="docs-toc">
+            <TableOfContents headings={headings} />
+          </aside>
+        )}
+      </div>
+    </div>
+  );
+}

package/app/routes.ts ADDED Viewed

@@ -0,0 +1,29 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { type RouteConfig, index, route } from '@react-router/dev/routes';
+// Docs occupy the site root: manifest slugs map 1:1 onto URLs, and one module
+// (docs.tsx) serves them all — "/" via the index route, everything else via the
+// splat, which reads the slug from params["*"]. Search lives in the site header
+// (CommandPalette, ⌘K), so there is no route for it.
+//
+// Under ssr:false every route exporting a loader must have prerendered paths,
+// so each route is included only when it has pages to serve: the index only
+// when there is a root page, the splat only when there are non-root pages.
+// Without this a single-page site fails the build. Content location comes from
+// the generated lectio.config.json, read via cwd (the build runs there).
+const { contentDir } = JSON.parse(
+  readFileSync(join(process.cwd(), 'lectio.config.json'), 'utf-8'),
+) as { contentDir: string };
+const manifest = JSON.parse(
+  readFileSync(join(contentDir, 'manifest.json'), 'utf-8'),
+) as { pages: Array<{ slug: string }> };
+const hasRoot = manifest.pages.some((page) => page.slug === '/');
+const hasNonRoot = manifest.pages.some((page) => page.slug !== '/');
+export default [
+  ...(hasRoot ? [index('routes/docs.tsx', { id: 'docs-index' })] : []),
+  ...(hasNonRoot ? [route('*', 'routes/docs.tsx')] : []),
+] satisfies RouteConfig;

package/app/site.config.ts ADDED Viewed

@@ -0,0 +1,8 @@
+// Site branding, the one place the app is not generic. Committed here with the
+// reference site's own values; the lectio CLI overwrites this file when it
+// materializes this same app for another repo, so everything under app/ stays
+// shared between the two.
+export const site = {
+  title: 'Lectio Docs',
+  githubUrl: 'https://github.com/losol/lectio-docs' as string | undefined,
+};

package/bin/lectio.mjs ADDED Viewed

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * lectio — run one command, get a docs site.
+ *
+ * `lectio build` in a repo with a docs.config.{ts,js,mjs}:
+ *
+ *   1. collects the configured sources (manifest + markdown)
+ *   2. builds the search index
+ *   3. materializes THIS package's own site app into .lectio/site — the same
+ *      app that ships as the demo (apps/site-builder), so there is no separate
+ *      template to keep in sync. React Router does not apply its app-source
+ *      transforms (the .server boundary, loader stripping) to files under
+ *      node_modules, so the app is copied out to a normal build dir here.
+ *   4. links the build dir's node_modules to THIS package's dependency dir —
+ *      dirname(realpath(<own package>)) holds the deps in both pnpm's
+ *      virtual-store layout and npm's flat layout — so the consumer installs
+ *      nothing beyond lectio-docs itself
+ *   5. runs the React Router build there (prerenders every page)
+ *   6. copies the static output to ./dist
+ *
+ * Spike quality: build command only, minimal argument handling.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const require = createRequire(import.meta.url);
+const command = process.argv[2];
+if (command !== 'build') {
+  console.error('Usage: lectio build');
+  process.exit(command ? 1 : 0);
+}
+const cwd = process.cwd();
+// --- 1. discover + load the user's docs config -----------------------------
+const configPath = ['docs.config.ts', 'docs.config.js', 'docs.config.mjs']
+  .map((name) => resolve(cwd, name))
+  .find((candidate) => existsSync(candidate));
+if (!configPath) {
+  console.error('No docs.config.{ts,js,mjs} found in the current directory.');
+  process.exit(1);
+}
+const config = (await import(pathToFileURL(configPath).href)).default;
+if (!config?.sources || !config?.output) {
+  console.error('The docs config must export { output, sources }.');
+  process.exit(1);
+}
+// The repo root is where you run this from — the dir holding docs.config. Every
+// source glob and edit-URL path is resolved relative to it (collect's rootDir).
+// We deliberately do NOT walk up to an ancestor .git: that made the base depend
+// on where a .git happened to sit above cwd, which breaks when the config lives
+// in a nested dir (e.g. examples/) or in some CI checkouts.
+const rootDir = cwd;
+// --- 2. collect + index -----------------------------------------------------
+const { collect } = await import('@eventuras/lectio-docs');
+const { buildSearchIndex } = await import('@eventuras/lectio-docs/build-index');
+await collect({ rootDir, config, configDir: cwd });
+const contentDir = resolve(cwd, config.output);
+// --- 3. materialize this package's site app --------------------------------
+// Copy app/ + wiring out of the package. Once installed, the package lives
+// under node_modules, where RR won't apply its app-source transforms — copying
+// to a normal dir restores the .server boundary and loader stripping.
+const siteDir = resolve(cwd, '.lectio/site');
+rmSync(siteDir, { recursive: true, force: true });
+mkdirSync(siteDir, { recursive: true });
+const pkgRoot = fileURLToPath(new URL('..', import.meta.url));
+cpSync(join(pkgRoot, 'app'), join(siteDir, 'app'), { recursive: true });
+cpSync(join(pkgRoot, 'react-router.config.ts'), join(siteDir, 'react-router.config.ts'));
+cpSync(join(pkgRoot, 'vite.config.ts'), join(siteDir, 'vite.config.ts'));
+// Minimal package.json for the build dir. Only isbot matters: react-router dev
+// auto-installs it when missing, which would hit the network mid-build.
+// Everything else resolves through the linked node_modules (step 4).
+writeFileSync(
+  join(siteDir, 'package.json'),
+  JSON.stringify({ name: 'lectio-site', private: true, type: 'module', dependencies: { isbot: '^5' } }, null, 2) + '\n',
+);
+// A self-contained tsconfig so esbuild (which transforms react-router.config.ts
+// and vite.config.ts) stops here instead of walking up into the consumer's
+// repo. Without it, a parent tsconfig — e.g. one that `extends` a base package
+// — gets picked up and can fail to resolve, breaking the build for reasons that
+// have nothing to do with the docs.
+writeFileSync(
+  join(siteDir, 'tsconfig.json'),
+  JSON.stringify(
+    {
+      compilerOptions: {
+        target: 'ES2022',
+        module: 'ESNext',
+        moduleResolution: 'bundler',
+        jsx: 'react-jsx',
+        skipLibCheck: true,
+      },
+    },
+    null,
+    2,
+  ) + '\n',
+);
+// Where the app reads content from, and the branding it renders. site.config.ts
+// was copied above with this repo's own branding; overwrite it with the
+// consumer's, so app/ stays generic and config-driven.
+writeFileSync(join(siteDir, 'lectio.config.json'), JSON.stringify({ contentDir }, null, 2) + '\n');
+writeFileSync(
+  join(siteDir, 'app', 'site.config.ts'),
+  `// Generated by lectio build — do not edit.
+export const site = {
+  title: ${JSON.stringify(config.site?.title ?? 'Docs')},
+  githubUrl: ${JSON.stringify(config.site?.githubUrl)} as string | undefined,
+};
+`,
+);
+mkdirSync(join(siteDir, 'public'), { recursive: true });
+await buildSearchIndex({
+  contentDir,
+  outputPath: join(siteDir, 'public', 'search-index.json'),
+  log: (message) => console.log(message),
+});
+// --- 4. dependency resolution via symlink -----------------------------------
+// Own package dir = parent of bin/. Where the deps live depends on layout:
+//  - workspace dev / npm with nesting: <own>/node_modules exists — use it
+//  - installed via pnpm: realpath resolves into the virtual store, whose
+//    parent dir holds this package's deps as siblings
+//  - npm flat: <own>/node_modules absent, dirname(realpath) is the flat
+//    node_modules that holds everything
+const ownPackageDir = realpathSync(pkgRoot);
+const ownNodeModules = join(ownPackageDir, 'node_modules');
+const depsDir = existsSync(ownNodeModules) ? ownNodeModules : dirname(ownPackageDir);
+// A REAL node_modules directory with one symlink per package — not a single
+// symlink to depsDir. Vite writes into node_modules (.vite-temp config
+// bundles, dep cache); with a whole-dir symlink those writes would land in
+// this package's own node_modules. Per-package links keep resolution working
+// while writes stay local to the materialized site.
+const siteModules = join(siteDir, 'node_modules');
+mkdirSync(siteModules, { recursive: true });
+for (const entry of readdirSync(depsDir)) {
+  if (entry.startsWith('.')) continue; // .bin, .vite-temp, .modules.yaml, …
+  if (entry.startsWith('@')) {
+    mkdirSync(join(siteModules, entry), { recursive: true });
+    for (const scoped of readdirSync(join(depsDir, entry))) {
+      symlinkSync(join(depsDir, entry, scoped), join(siteModules, entry, scoped), 'dir');
+    }
+  } else {
+    symlinkSync(join(depsDir, entry), join(siteModules, entry), 'dir');
+  }
+}
+// --- 5. run the React Router build ------------------------------------------
+const rrDevPkg = require.resolve('@react-router/dev/package.json');
+const rrBin = join(dirname(rrDevPkg), require(rrDevPkg).bin['react-router']);
+const result = spawnSync(process.execPath, [rrBin, 'build'], {
+  cwd: siteDir,
+  stdio: 'inherit',
+});
+if (result.status !== 0) process.exit(result.status ?? 1);
+// --- 6. static output --------------------------------------------------------
+const outDir = resolve(cwd, 'dist');
+rmSync(outDir, { recursive: true, force: true });
+cpSync(join(siteDir, 'build', 'client'), outDir, { recursive: true });
+console.log(`\nDocs site built → ${outDir}`);

package/package.json ADDED Viewed

@@ -0,0 +1,42 @@
+{
+  "name": "lectio-docs",
+  "version": "0.1.0",
+  "description": "Run one command, get a docs site: collects scattered repo docs and builds a static, searchable site.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "lectio": "./bin/lectio.mjs"
+  },
+  "files": [
+    "app",
+    "bin",
+    "react-router.config.ts",
+    "vite.config.ts"
+  ],
+  "dependencies": {
+    "@eventuras/markdown": "^0.13.0",
+    "@eventuras/ratio-ui": "^2.15.0",
+    "@react-router/dev": "8.2.0",
+    "@react-router/node": "8.2.0",
+    "isbot": "^5.2.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-router": "8.2.0",
+    "vite": "^8.1.5",
+    "@eventuras/lectio-docs": "0.3.0",
+    "@eventuras/lectio-docs-react": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "collect": "node scripts/collect.mjs",
+    "dev": "pnpm collect && react-router dev",
+    "build": "pnpm collect && react-router build",
+    "preview": "vite preview",
+    "typecheck": "pnpm collect && react-router typegen && tsc --noEmit"
+  }
+}

package/react-router.config.ts ADDED Viewed

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Config } from '@react-router/dev/config';
+/**
+ * Static site. Every collected page is prerendered at build time, so there is
+ * no server to run — the output is plain HTML on a CDN.
+ *
+ * Prerendering still executes the loaders, but in Node at build time, which is
+ * why `content.server.ts` can keep reading the collected markdown from disk.
+ * The path list is simply the manifest's slugs: collect() has already decided
+ * what exists, and slugs map 1:1 onto URLs.
+ *
+ * Content location comes from the generated lectio.config.json, read via cwd —
+ * the same file routes.ts and content.server.ts read. Written next to the build
+ * by this app's collect script (the demo) or by the lectio CLI when it
+ * materializes this app for another repo, so the wiring is identical in both.
+ */
+export default {
+  ssr: false,
+  async prerender() {
+    const { contentDir } = JSON.parse(
+      readFileSync(join(process.cwd(), 'lectio.config.json'), 'utf-8'),
+    ) as { contentDir: string };
+    const manifest = JSON.parse(
+      readFileSync(join(contentDir, 'manifest.json'), 'utf-8'),
+    ) as { pages: Array<{ slug: string }> };
+    return manifest.pages.map((page) => page.slug);
+  },
+} satisfies Config;

package/vite.config.ts ADDED Viewed

@@ -0,0 +1,6 @@
+import { reactRouter } from '@react-router/dev/vite';
+import { defineConfig } from 'vite';
+export default defineConfig({
+  plugins: [reactRouter()],
+});