@beatzball/create-litro 0.1.4 → 0.2.0

package/recipes/starlight/template/src/components/starlight-sidebar.ts

@@ -0,0 +1,125 @@
+import { LitElement, html, css } from 'lit';
+import { customElement } from 'lit/decorators.js';
+
+export interface SidebarItem {
+  label: string;
+  slug: string;
+  badge?: { text: string; variant?: string };
+}
+
+export interface SidebarGroup {
+  label: string;
+  items: SidebarItem[];
+}
+
+/**
+ * <starlight-sidebar .groups=${sidebar} currentSlug="getting-started">
+ *   Renders grouped navigation links for the docs sidebar.
+ *   The active item (matching currentSlug) is highlighted with aria-current.
+ */
+@customElement('starlight-sidebar')
+export class StarlightSidebar extends LitElement {
+  static override properties = {
+    groups: { type: Array },
+    currentSlug: { type: String },
+  };
+
+  static override styles = css`
+    :host {
+      display: block;
+    }
+
+    nav {
+      padding: 1rem 0;
+    }
+
+    .group {
+      margin-bottom: 1.5rem;
+    }
+
+    .group-label {
+      font-size: var(--sl-text-xs, 0.75rem);
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.1em;
+      color: var(--sl-color-gray-4, #757575);
+      padding: 0 1rem;
+      margin: 0 0 0.5rem;
+    }
+
+    ul {
+      list-style: none;
+      padding: 0;
+      margin: 0;
+    }
+
+    li {
+      margin: 0;
+    }
+
+    a {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 0.35rem 1rem;
+      font-size: var(--sl-text-sm, 0.875rem);
+      color: var(--sl-color-gray-5, #4b4b4b);
+      text-decoration: none;
+      border-left: 2px solid transparent;
+      transition: color 0.15s, background-color 0.15s;
+    }
+
+    a:hover {
+      color: var(--sl-color-text, #23262f);
+      background-color: var(--sl-color-gray-2, #e8e8e8);
+    }
+
+    a[aria-current='page'] {
+      color: var(--sl-color-accent, #7c3aed);
+      border-left-color: var(--sl-color-accent, #7c3aed);
+      background-color: var(--sl-color-accent-low, #ede9fe);
+      font-weight: 600;
+    }
+
+    .badge {
+      display: inline-block;
+      padding: 0.1em 0.45em;
+      font-size: var(--sl-text-xs, 0.75rem);
+      font-weight: 600;
+      border-radius: 9999px;
+      background-color: var(--sl-color-accent-low, #ede9fe);
+      color: var(--sl-color-accent-high, #5b21b6);
+      margin-left: 0.5rem;
+    }
+  `;
+
+  groups: SidebarGroup[] = [];
+  currentSlug = '';
+
+  override render() {
+    return html`
+      <nav aria-label="Site navigation">
+        ${this.groups.map(group => html`
+          <div class="group">
+            <p class="group-label">${group.label}</p>
+            <ul>
+              ${group.items.map(item => html`
+                <li>
+                  <a
+                    href="/docs/${item.slug}"
+                    aria-current="${this.currentSlug === item.slug ? 'page' : 'false'}"
+                  >
+                    <span>${item.label}</span>
+                    ${item.badge ? html`<span class="badge">${item.badge.text}</span>` : ''}
+                  </a>
+                </li>
+              `)}
+            </ul>
+          </div>
+        `)}
+      </nav>
+    `;
+  }
+}
+
+export default StarlightSidebar;

package/recipes/starlight/template/src/components/starlight-toc.ts

@@ -0,0 +1,133 @@
+import { LitElement, html, css } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import type { TocEntry } from '../extract-headings.js';
+
+/**
+ * <starlight-toc .entries=${toc}>
+ *   Renders the table of contents as anchor links.
+ *   Active section highlighting is handled by CSS :target pseudo-class.
+ */
+@customElement('starlight-toc')
+export class StarlightToc extends LitElement {
+  static override properties = {
+    entries: { type: Array },
+  };
+
+  static override styles = css`
+    :host {
+      display: block;
+    }
+
+    nav {
+      position: sticky;
+      top: calc(var(--sl-nav-height, 3.5rem) + 1rem);
+      max-height: calc(100vh - var(--sl-nav-height, 3.5rem) - 2rem);
+      overflow-y: auto;
+      padding: 0 0.5rem;
+    }
+
+    h2 {
+      font-size: var(--sl-text-xs, 0.75rem);
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.1em;
+      color: var(--sl-color-gray-4, #757575);
+      margin: 0 0 0.75rem;
+      padding: 0;
+      border: none;
+    }
+
+    ul {
+      list-style: none;
+      padding: 0;
+      margin: 0;
+    }
+
+    li {
+      margin: 0;
+    }
+
+    a {
+      display: block;
+      padding: 0.2rem 0;
+      font-size: var(--sl-text-sm, 0.875rem);
+      color: var(--sl-color-gray-4, #757575);
+      text-decoration: none;
+      transition: color 0.15s;
+      border-left: 2px solid transparent;
+    }
+
+    a:hover {
+      color: var(--sl-color-text, #23262f);
+    }
+
+    /* Depth indentation */
+    .depth-2 a { padding-left: 0.75rem; }
+    .depth-3 a { padding-left: 1.5rem; }
+    .depth-4 a { padding-left: 2.25rem; }
+
+    /* Active via [aria-current] set by the click handler */
+    li a[aria-current='true'] {
+      color: var(--sl-color-accent, #7c3aed);
+      border-left-color: var(--sl-color-accent, #7c3aed);
+    }
+  `;
+
+  entries: TocEntry[] = [];
+
+  /**
+   * Click handler for TOC anchor links.
+   *
+   * Heading elements rendered via unsafeHTML live inside shadow roots that
+   * native fragment navigation and document.getElementById() cannot reach.
+   * Instead of relying on the browser's default hash navigation (which also
+   * fires popstate and re-renders the page component with no data), we:
+   *   1. Prevent the default navigation.
+   *   2. Walk the shadow tree to find the target element.
+   *   3. Scroll to it smoothly.
+   *   4. Update the URL hash via pushState (does not fire popstate).
+   */
+  private _handleClick(e: MouseEvent, slug: string) {
+    e.preventDefault();
+    const target = this._findDeep(document, slug);
+    if (target) target.scrollIntoView({ behavior: 'smooth' });
+    history.pushState(null, '', `#${slug}`);
+  }
+
+  /** Recursively searches shadow roots for an element matching the CSS id selector. */
+  private _findDeep(root: Document | ShadowRoot | Element, id: string): Element | null {
+    const sel = `#${CSS.escape(id)}`;
+    const direct = root.querySelector(sel);
+    if (direct) return direct;
+    for (const el of root.querySelectorAll('*')) {
+      if (el.shadowRoot) {
+        const found = this._findDeep(el.shadowRoot, id);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  override render() {
+    if (!this.entries.length) return html``;
+    const currentHash = typeof location !== 'undefined' ? location.hash : '';
+    return html`
+      <nav aria-label="On this page">
+        <h2>On this page</h2>
+        <ul>
+          ${this.entries.map(entry => html`
+            <li class="depth-${entry.depth}">
+              <a
+                href="#${entry.slug}"
+                aria-current="${currentHash === '#' + entry.slug ? 'true' : 'false'}"
+                @click=${(e: MouseEvent) => this._handleClick(e, entry.slug)}
+              >${entry.text}</a>
+            </li>
+          `)}
+        </ul>
+      </nav>
+    `;
+  }
+}
+
+export default StarlightToc;

package/recipes/starlight/template/src/date-utils.ts

@@ -0,0 +1,20 @@
+/**
+ * Formats a Date or date string into a human-readable form.
+ * Uses the `en-US` locale with month-name style (e.g. "January 15, 2026").
+ */
+export function formatDate(date: Date | string): string {
+  const d = date instanceof Date ? date : new Date(date as string);
+  return d.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  });
+}
+
+/**
+ * Returns an ISO 8601 string (e.g. "2026-01-15") suitable for a `datetime` attribute.
+ */
+export function isoDate(date: Date | string): string {
+  const d = date instanceof Date ? date : new Date(date as string);
+  return d.toISOString().slice(0, 10);
+}

package/recipes/starlight/template/src/extract-headings.ts

@@ -0,0 +1,68 @@
+export interface TocEntry {
+  depth: number;
+  text: string;
+  slug: string;
+}
+
+/**
+ * Extracts h2–h4 headings from raw Markdown source.
+ * Returns an array of TocEntry objects suitable for rendering a table of contents.
+ */
+export function extractHeadings(rawMarkdown: string): TocEntry[] {
+  const headings: TocEntry[] = [];
+  const lines = rawMarkdown.split('\n');
+
+  for (const line of lines) {
+    const match = line.match(/^(#{2,4})\s+(.+)$/);
+    if (!match) continue;
+
+    const depth = match[1].length;
+    const text = match[2].trim().replace(/\s*\{[^}]*\}\s*$/, ''); // strip {#custom-id} syntax
+    const slug = text
+      .toLowerCase()
+      .replace(/[^\w\s-]/g, '')
+      .trim()
+      .replace(/\s+/g, '-')
+      .replace(/-+/g, '-');
+
+    headings.push({ depth, text, slug });
+  }
+
+  return headings;
+}
+
+/**
+ * Post-processes rendered HTML to inject `id` attributes on h2–h4 elements,
+ * matching the slugs produced by `extractHeadings()`.
+ * Enables anchor-link navigation from the table of contents.
+ */
+export function addHeadingIds(html: string): string {
+  const counters: Record<string, number> = {};
+
+  return html.replace(
+    /<(h[2-4])([^>]*)>([\s\S]*?)<\/h[2-4]>/gi,
+    (_match, tag: string, attrs: string, content: string) => {
+      // Strip HTML tags from content to get plain text
+      const text = content.replace(/<[^>]+>/g, '').trim().replace(/\s*\{[^}]*\}\s*$/, '');
+      let slug = text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, '')
+        .trim()
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-');
+
+      // Deduplicate: if the same slug appears twice, append -2, -3, etc.
+      counters[slug] = (counters[slug] ?? 0) + 1;
+      if (counters[slug] > 1) {
+        slug = `${slug}-${counters[slug]}`;
+      }
+
+      // Avoid double-injecting if an id already exists
+      if (/\bid=/.test(attrs)) {
+        return `<${tag}${attrs}>${content}</${tag}>`;
+      }
+
+      return `<${tag}${attrs} id="${slug}">${content}</${tag}>`;
+    },
+  );
+}

package/recipes/starlight/template/src/route-meta.ts

@@ -0,0 +1,16 @@
+/**
+ * HTML injected into every page's <head> via routeMeta.head.
+ *
+ * Order matters:
+ *   1. Stylesheet link — loaded asynchronously by the browser; must come before
+ *      the FOUC-prevention script so --sl-* tokens are available immediately.
+ *   2. Inline script — synchronous, runs before first paint to set data-theme
+ *      from localStorage, preventing a flash of the wrong theme on reload.
+ */
+export const starlightHead = [
+  '<link rel="stylesheet" href="/styles/starlight.css" />',
+  '<script>(function(){',
+  'var t=localStorage.getItem("sl-theme")||"light";',
+  'document.documentElement.setAttribute("data-theme",t);',
+  '})();</script>',
+].join('');

package/recipes/starlight/template/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist", ".nitro"]
+}

package/recipes/starlight/template/vite.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vite';
+import litroContentPlugin from '@beatzball/litro/vite';
+
+export default defineConfig({
+  plugins: [litroContentPlugin()],
+  base: '/_litro/',
+  resolve: {
+    conditions: ['source', 'browser', 'module', 'import', 'default'],
+  },
+  build: {
+    outDir: 'dist/client',
+    rollupOptions: {
+      input: 'app.ts',
+      output: {
+        entryFileNames: '[name].js',
+      },
+    },
+  },
+});

package/src/scaffold.test.ts

@@ -225,4 +225,152 @@ describe('scaffold', () => {
         .rejects.toThrow();
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // starlight recipe
+  // ---------------------------------------------------------------------------
+
+  it('starlight recipe writes litro.recipe.json with ssg mode', async () => {
+    await withTmpDir(async (dir) => {
+      const targetDir = join(dir, 'my-docs');
+      await scaffold('starlight', { projectName: 'my-docs', mode: 'ssg' }, targetDir);
+
+      const { existsSync } = await import('node:fs');
+      expect(existsSync(join(targetDir, 'litro.recipe.json'))).toBe(true);
+
+      const manifest = JSON.parse(await readFile(join(targetDir, 'litro.recipe.json'), 'utf-8')) as Record<string, unknown>;
+      expect(manifest.recipe).toBe('starlight');
+      expect(manifest.mode).toBe('ssg');
+      expect(manifest.contentDir).toBe('content');
+    });
+  });
+
+  it('starlight recipe writes all expected files', async () => {
+    await withTmpDir(async (dir) => {
+      const targetDir = join(dir, 'my-docs');
+      await scaffold('starlight', { projectName: 'my-docs', mode: 'ssg' }, targetDir);
+
+      const { existsSync } = await import('node:fs');
+      // Core config
+      expect(existsSync(join(targetDir, 'package.json'))).toBe(true);
+      expect(existsSync(join(targetDir, 'tsconfig.json'))).toBe(true);
+      expect(existsSync(join(targetDir, 'nitro.config.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'vite.config.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'app.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, '.gitignore'))).toBe(true);
+      expect(existsSync(join(targetDir, 'litro.recipe.json'))).toBe(true);
+      // Server
+      expect(existsSync(join(targetDir, 'server/starlight.config.js'))).toBe(true);
+      expect(existsSync(join(targetDir, 'server/routes/[...].ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'server/middleware/vite-dev.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'server/stubs/page-manifest.ts'))).toBe(true);
+      // Pages
+      expect(existsSync(join(targetDir, 'pages/index.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'pages/docs/[slug].ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'pages/blog/index.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'pages/blog/[slug].ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'pages/blog/tags/[tag].ts'))).toBe(true);
+      // Utilities
+      expect(existsSync(join(targetDir, 'src/extract-headings.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'src/date-utils.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'src/route-meta.ts'))).toBe(true);
+      // Components
+      expect(existsSync(join(targetDir, 'src/components/starlight-page.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'src/components/starlight-header.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'src/components/starlight-sidebar.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'src/components/starlight-toc.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'src/components/sl-card.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'src/components/sl-card-grid.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'src/components/sl-badge.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'src/components/sl-aside.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'src/components/sl-tabs.ts'))).toBe(true);
+      expect(existsSync(join(targetDir, 'src/components/sl-tab-item.ts'))).toBe(true);
+      // Content
+      expect(existsSync(join(targetDir, 'content/docs/.11tydata.json'))).toBe(true);
+      expect(existsSync(join(targetDir, 'content/docs/getting-started.md'))).toBe(true);
+      expect(existsSync(join(targetDir, 'content/blog/.11tydata.json'))).toBe(true);
+      expect(existsSync(join(targetDir, 'content/blog/welcome.md'))).toBe(true);
+      // Public
+      expect(existsSync(join(targetDir, 'public/styles/starlight.css'))).toBe(true);
+      // Data
+      expect(existsSync(join(targetDir, '_data/metadata.js'))).toBe(true);
+    });
+  });
+
+  it('starlight recipe interpolates {{projectName}} in package.json', async () => {
+    await withTmpDir(async (dir) => {
+      const targetDir = join(dir, 'awesome-docs');
+      await scaffold('starlight', { projectName: 'awesome-docs', mode: 'ssg' }, targetDir);
+
+      const pkg = JSON.parse(await readFile(join(targetDir, 'package.json'), 'utf-8')) as Record<string, unknown>;
+      expect(pkg.name).toBe('awesome-docs');
+    });
+  });
+
+  it('starlight recipe interpolates {{projectName}} in server/starlight.config.js', async () => {
+    await withTmpDir(async (dir) => {
+      const targetDir = join(dir, 'my-docs-site');
+      await scaffold('starlight', { projectName: 'my-docs-site', mode: 'ssg' }, targetDir);
+
+      const config = await readFile(join(targetDir, 'server/starlight.config.js'), 'utf-8');
+      expect(config).toContain('my-docs-site');
+      expect(config).not.toContain('{{projectName}}');
+    });
+  });
+
+  it('starlight recipe has no un-interpolated {{ }} in any output file', async () => {
+    await withTmpDir(async (dir) => {
+      const targetDir = join(dir, 'my-docs');
+      await scaffold('starlight', { projectName: 'my-docs', mode: 'ssg' }, targetDir);
+
+      const binaryExts = new Set(['.png', '.jpg', '.jpeg', '.gif', '.ico', '.webp', '.svg',
+        '.woff', '.woff2', '.ttf', '.eot', '.otf', '.pdf', '.zip', '.gz', '.tar', '.gitkeep']);
+
+      async function collectFiles(d: string): Promise<string[]> {
+        const { readdir: rd } = await import('node:fs/promises');
+        const entries = await rd(d, { withFileTypes: true });
+        const results: string[] = [];
+        for (const e of entries) {
+          const p = join(d, e.name);
+          if (e.isDirectory()) results.push(...(await collectFiles(p)));
+          else results.push(p);
+        }
+        return results;
+      }
+
+      const files = await collectFiles(targetDir);
+      for (const file of files) {
+        const extPart = file.includes('.') ? `.${file.split('.').pop()}` : '';
+        if (binaryExts.has(extPart.toLowerCase())) continue;
+        const content = await readFile(file, 'utf-8');
+        const matches = content.match(/\{\{[^}]+\}\}/g);
+        if (matches) {
+          throw new Error(`Un-interpolated placeholder in ${file}: ${matches.join(', ')}`);
+        }
+      }
+    });
+  });
+
+  it('starlight recipe page files use plain <a> tags, not <litro-link>', async () => {
+    // SSG pages must use <a> for full-page-reload navigation so each pre-rendered
+    // page loads its own __litro_data__. <litro-link> triggers SPA navigation which
+    // leaves serverData=null on the navigated page (no __litro_data__ in DOM).
+    await withTmpDir(async (dir) => {
+      const targetDir = join(dir, 'my-docs');
+      await scaffold('starlight', { projectName: 'my-docs', mode: 'ssg' }, targetDir);
+
+      const pageFiles = [
+        join(targetDir, 'pages/index.ts'),
+        join(targetDir, 'pages/docs/[slug].ts'),
+        join(targetDir, 'pages/blog/index.ts'),
+        join(targetDir, 'pages/blog/[slug].ts'),
+        join(targetDir, 'pages/blog/tags/[tag].ts'),
+      ];
+
+      for (const file of pageFiles) {
+        const content = await readFile(file, 'utf-8');
+        expect(content, `${file} should not contain <litro-link>`).not.toContain('litro-link');
+      }
+    });
+  });
 });