@beatzball/create-litro 0.1.4 → 0.2.0

package/recipes/starlight/template/pages/docs/[slug].ts

@@ -0,0 +1,147 @@
+import { html } from 'lit';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import { customElement } from 'lit/decorators.js';
+import { LitroPage } from '@beatzball/litro/runtime';
+import { definePageData } from '@beatzball/litro';
+import { createError } from 'h3';
+import type { Post } from 'litro:content';
+import { getPosts } from 'litro:content';
+import { siteConfig } from '../../server/starlight.config.js';
+import { extractHeadings, addHeadingIds } from '../../src/extract-headings.js';
+import { starlightHead } from '../../src/route-meta.js';
+
+// Register components used in render()
+import '../../src/components/starlight-page.js';
+
+export interface DocPageData {
+  doc: Post;
+  body: string;
+  toc: Array<{ depth: number; text: string; slug: string }>;
+  sidebar: typeof siteConfig.sidebar;
+  siteTitle: string;
+  currentSlug: string;
+  prevDoc: { label: string; href: string } | null;
+  nextDoc: { label: string; href: string } | null;
+  nav: typeof siteConfig.nav;
+  editUrl: string | null;
+}
+
+function computePrevNext(
+  sidebar: typeof siteConfig.sidebar,
+  currentSlug: string,
+): { prevDoc: DocPageData['prevDoc']; nextDoc: DocPageData['nextDoc'] } {
+  const flat = sidebar.flatMap(g => g.items);
+  const idx = flat.findIndex(item => item.slug === currentSlug);
+  return {
+    prevDoc: idx > 0
+      ? { label: flat[idx - 1].label, href: `/docs/${flat[idx - 1].slug}` }
+      : null,
+    nextDoc: idx < flat.length - 1
+      ? { label: flat[idx + 1].label, href: `/docs/${flat[idx + 1].slug}` }
+      : null,
+  };
+}
+
+export const pageData = definePageData(async (event) => {
+  const slug = event.context.params?.slug ?? '';
+
+  // Content URLs are /content/docs/<slug> (contentDir = 'content', so
+  // dirname is project root, and paths include the 'content/' prefix in the URL).
+  const posts = await getPosts();
+  const doc = posts.find(p => p.url === `/content/docs/${slug}`);
+
+  if (!doc) {
+    throw createError({ statusCode: 404, message: `Doc not found: ${slug}` });
+  }
+
+  const toc = extractHeadings(doc.rawBody);
+  const body = addHeadingIds(doc.body);
+  const { prevDoc, nextDoc } = computePrevNext(siteConfig.sidebar, slug);
+  const editUrl = siteConfig.editUrlBase
+    ? `${siteConfig.editUrlBase}/content/docs/${slug}.md`
+    : null;
+
+  return {
+    doc,
+    body,
+    toc,
+    sidebar: siteConfig.sidebar,
+    siteTitle: siteConfig.title,
+    currentSlug: slug,
+    prevDoc,
+    nextDoc,
+    nav: siteConfig.nav,
+    editUrl,
+  } satisfies DocPageData;
+});
+
+export async function generateRoutes(): Promise<string[]> {
+  const posts = await getPosts();
+  return posts
+    .filter(p => p.url.startsWith('/content/docs/'))
+    .map(p => '/docs' + p.url.slice('/content/docs'.length));
+}
+
+export const routeMeta = {
+  head: starlightHead,
+  title: 'Docs — {{projectName}}',
+};
+
+@customElement('page-docs-slug')
+export class DocPage extends LitroPage {
+  override render() {
+    const data = this.serverData as DocPageData | null;
+    if (!data?.doc) return html`<p>Loading&hellip;</p>`;
+
+    return html`
+      <starlight-page
+        siteTitle="${data.siteTitle}"
+        pageTitle="${data.doc.title}"
+        .nav="${data.nav}"
+        .sidebar="${data.sidebar}"
+        .toc="${data.toc}"
+        currentSlug="${data.currentSlug}"
+        currentPath="/docs/${data.currentSlug}"
+      >
+        <div slot="content">
+          <!-- unsafeHTML renders the Markdown-generated HTML directly.
+               The content/docs directory is trusted-author-only; do not place
+               user-submitted or untrusted content here without sanitizing. -->
+          ${unsafeHTML(data.body)}
+
+          ${data.prevDoc || data.nextDoc ? html`
+            <nav style="
+              display:flex;
+              justify-content:space-between;
+              padding-top:2rem;
+              margin-top:2rem;
+              border-top:1px solid var(--sl-color-border);
+              font-size:var(--sl-text-sm);
+            " aria-label="Previous and next pages">
+              ${data.prevDoc ? html`
+                <a href="${data.prevDoc.href}" style="color:var(--sl-color-accent);text-decoration:none;">
+                  ← ${data.prevDoc.label}
+                </a>
+              ` : html`<span></span>`}
+              ${data.nextDoc ? html`
+                <a href="${data.nextDoc.href}" style="color:var(--sl-color-accent);text-decoration:none;">
+                  ${data.nextDoc.label} →
+                </a>
+              ` : ''}
+            </nav>
+          ` : ''}
+
+          ${data.editUrl ? html`
+            <p style="margin-top:1.5rem;font-size:var(--sl-text-xs);color:var(--sl-color-gray-4);">
+              <a href="${data.editUrl}" style="color:var(--sl-color-accent);" target="_blank" rel="noopener">
+                Edit this page
+              </a>
+            </p>
+          ` : ''}
+        </div>
+      </starlight-page>
+    `;
+  }
+}
+
+export default DocPage;

package/recipes/starlight/template/pages/index.ts

@@ -0,0 +1,135 @@
+import { html } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import { LitroPage } from '@beatzball/litro/runtime';
+import { definePageData } from '@beatzball/litro';
+import { getGlobalData } from 'litro:content';
+import { siteConfig } from '../server/starlight.config.js';
+import { starlightHead } from '../src/route-meta.js';
+
+// Register components used in render()
+import '../src/components/starlight-header.js';
+import '../src/components/sl-card.js';
+import '../src/components/sl-card-grid.js';
+
+export interface SplashData {
+  siteTitle: string;
+  description: string;
+  nav: Array<{ label: string; href: string }>;
+  features: Array<{ title: string; description: string; icon?: string }>;
+}
+
+export const pageData = definePageData(async (_event) => {
+  const metadata = await getGlobalData();
+  return {
+    siteTitle: String(metadata.title ?? siteConfig.title),
+    description: String(metadata.description ?? siteConfig.description),
+    nav: siteConfig.nav,
+    features: [
+      {
+        icon: '📄',
+        title: 'Docs',
+        description: 'Structured documentation with sidebar, TOC, and prev/next navigation.',
+      },
+      {
+        icon: '✍️',
+        title: 'Blog',
+        description: 'Write posts in Markdown. Tags, dates, and listing pages auto-generated.',
+      },
+      {
+        icon: '🎨',
+        title: 'Theming',
+        description: 'Light and dark mode via CSS custom properties. Zero JavaScript required.',
+      },
+      {
+        icon: '⚡',
+        title: 'Static',
+        description: 'Pre-rendered to plain HTML. Deploy to any CDN with no server required.',
+      },
+    ],
+  } satisfies SplashData;
+});
+
+export const routeMeta = {
+  head: starlightHead,
+  title: '{{projectName}}',
+};
+
+@customElement('page-home')
+export class SplashPage extends LitroPage {
+  override render() {
+    const data = this.serverData as SplashData | null;
+    const { siteTitle = '{{projectName}}', description = '', nav = [], features = [] } = data ?? {};
+
+    return html`
+      <div style="min-height:100vh;display:flex;flex-direction:column;">
+        <starlight-header
+          siteTitle="${siteTitle}"
+          .nav="${nav}"
+          currentPath="/"
+        ></starlight-header>
+        <main style="
+          flex:1;
+          max-width:56rem;
+          margin:0 auto;
+          padding:4rem 1.5rem 3rem;
+          width:100%;
+        ">
+          <section style="text-align:center;margin-bottom:4rem;">
+            <h1 style="
+              font-size:clamp(2rem,5vw,3.5rem);
+              font-weight:800;
+              color:var(--sl-color-text);
+              margin:0 0 1rem;
+              line-height:1.1;
+            ">${siteTitle}</h1>
+            ${description ? html`
+              <p style="
+                font-size:var(--sl-text-xl);
+                color:var(--sl-color-gray-4);
+                max-width:36rem;
+                margin:0 auto 2.5rem;
+                line-height:1.6;
+              ">${description}</p>
+            ` : ''}
+            <div style="display:flex;gap:1rem;justify-content:center;flex-wrap:wrap;">
+              <a href="/docs/getting-started" style="
+                display:inline-block;
+                padding:0.6rem 1.5rem;
+                background:var(--sl-color-accent);
+                color:var(--sl-color-text-invert,#fff);
+                border-radius:var(--sl-border-radius);
+                font-weight:600;
+                text-decoration:none;
+                font-size:var(--sl-text-base);
+              ">Get Started</a>
+              <a href="/blog" style="
+                display:inline-block;
+                padding:0.6rem 1.5rem;
+                border:1px solid var(--sl-color-border);
+                color:var(--sl-color-text);
+                border-radius:var(--sl-border-radius);
+                font-weight:600;
+                text-decoration:none;
+                font-size:var(--sl-text-base);
+              ">Blog</a>
+            </div>
+          </section>
+
+          <section>
+            <sl-card-grid>
+              ${features.map(f => html`
+                <sl-card
+                  icon="${f.icon ?? ''}"
+                  title="${f.title}"
+                  description="${f.description}"
+                ></sl-card>
+              `)}
+            </sl-card-grid>
+          </section>
+        </main>
+      </div>
+    `;
+  }
+}
+
+export default SplashPage;

package/recipes/starlight/template/public/styles/starlight.css

@@ -0,0 +1,215 @@
+/* Starlight design tokens — light mode defaults */
+:root {
+  --sl-color-white: #fff;
+  --sl-color-black: #23262f;
+  --sl-color-gray-1: #f6f6f6;
+  --sl-color-gray-2: #e8e8e8;
+  --sl-color-gray-3: #bdbdbd;
+  --sl-color-gray-4: #757575;
+  --sl-color-gray-5: #4b4b4b;
+  --sl-color-gray-6: #2a2a2a;
+
+  --sl-color-accent: #7c3aed;
+  --sl-color-accent-high: #5b21b6;
+  --sl-color-accent-low: #ede9fe;
+
+  --sl-color-note: #1d4ed8;
+  --sl-color-tip: #15803d;
+  --sl-color-caution: #b45309;
+  --sl-color-danger: #b91c1c;
+
+  --sl-color-text: var(--sl-color-black);
+  --sl-color-text-accent: var(--sl-color-accent);
+  --sl-color-text-invert: var(--sl-color-white);
+  --sl-color-bg: var(--sl-color-white);
+  --sl-color-bg-sidebar: var(--sl-color-gray-1);
+  --sl-color-bg-nav: var(--sl-color-white);
+  --sl-color-bg-inline-code: var(--sl-color-gray-2);
+  --sl-color-border: var(--sl-color-gray-2);
+
+  --sl-font-sans: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --sl-font-mono: ui-monospace, "Cascadia Code", "Fira Code", monospace;
+
+  --sl-text-xs:   0.75rem;
+  --sl-text-sm:   0.875rem;
+  --sl-text-base: 1rem;
+  --sl-text-lg:   1.125rem;
+  --sl-text-xl:   1.25rem;
+  --sl-text-2xl:  1.5rem;
+  --sl-text-3xl:  1.875rem;
+  --sl-text-4xl:  2.25rem;
+
+  --sl-nav-height: 3.5rem;
+  --sl-sidebar-width: 16rem;
+  --sl-toc-width: 14rem;
+  --sl-content-width: 48rem;
+  --sl-content-pad-x: 1.5rem;
+  --sl-content-pad-y: 2rem;
+
+  --sl-shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.08);
+  --sl-shadow-md: 0 4px 16px rgba(0, 0, 0, 0.12);
+
+  --sl-border-radius: 0.375rem;
+  --sl-border-radius-sm: 0.25rem;
+}
+
+/* Dark mode overrides */
+[data-theme='dark'] {
+  --sl-color-text: #f0f0f0;
+  --sl-color-bg: #17181c;
+  --sl-color-bg-sidebar: #1e1f24;
+  --sl-color-bg-nav: #17181c;
+  --sl-color-bg-inline-code: #2a2b30;
+  --sl-color-border: #2e2f35;
+
+  --sl-color-gray-1: #2a2b30;
+  --sl-color-gray-2: #35363d;
+  --sl-color-gray-3: #5a5b63;
+  --sl-color-gray-4: #8a8b94;
+  --sl-color-gray-5: #c0c1cb;
+  --sl-color-gray-6: #e8e9f0;
+
+  --sl-color-accent: #a78bfa;
+  --sl-color-accent-high: #c4b5fd;
+  --sl-color-accent-low: #2e1b54;
+
+  --sl-color-note: #60a5fa;
+  --sl-color-tip: #4ade80;
+  --sl-color-caution: #fbbf24;
+  --sl-color-danger: #f87171;
+}
+
+/* Base reset */
+*, *::before, *::after {
+  box-sizing: border-box;
+}
+
+html {
+  font-family: var(--sl-font-sans);
+  font-size: var(--sl-text-base);
+  color: var(--sl-color-text);
+  background-color: var(--sl-color-bg);
+  -webkit-font-smoothing: antialiased;
+  scroll-behavior: smooth;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+}
+
+/* Typography reset for content areas */
+h1, h2, h3, h4, h5, h6 {
+  margin-top: 1.5em;
+  margin-bottom: 0.5em;
+  font-weight: 600;
+  line-height: 1.25;
+  color: var(--sl-color-text);
+}
+
+h1 { font-size: var(--sl-text-4xl); }
+h2 { font-size: var(--sl-text-2xl); border-bottom: 1px solid var(--sl-color-border); padding-bottom: 0.25em; }
+h3 { font-size: var(--sl-text-xl); }
+h4 { font-size: var(--sl-text-lg); }
+
+p {
+  margin-top: 0;
+  margin-bottom: 1rem;
+  line-height: 1.7;
+}
+
+a {
+  color: var(--sl-color-text-accent);
+  text-decoration: none;
+}
+
+a:hover {
+  text-decoration: underline;
+}
+
+code {
+  font-family: var(--sl-font-mono);
+  font-size: 0.875em;
+  background-color: var(--sl-color-bg-inline-code);
+  border: 1px solid var(--sl-color-border);
+  border-radius: var(--sl-border-radius-sm);
+  padding: 0.15em 0.4em;
+}
+
+pre {
+  background-color: var(--sl-color-gray-6);
+  color: var(--sl-color-gray-1);
+  border-radius: var(--sl-border-radius);
+  padding: 1rem 1.25rem;
+  overflow-x: auto;
+  margin: 1.5rem 0;
+  font-size: var(--sl-text-sm);
+  line-height: 1.6;
+}
+
+[data-theme='dark'] pre {
+  background-color: #0d0e11;
+  color: #e2e4e9;
+}
+
+pre code {
+  background: none;
+  border: none;
+  padding: 0;
+  font-size: inherit;
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 1.5rem 0;
+  font-size: var(--sl-text-sm);
+}
+
+th, td {
+  border: 1px solid var(--sl-color-border);
+  padding: 0.5rem 0.75rem;
+  text-align: left;
+}
+
+th {
+  background-color: var(--sl-color-gray-1);
+  font-weight: 600;
+}
+
+[data-theme='dark'] th {
+  background-color: var(--sl-color-gray-1);
+}
+
+ul, ol {
+  padding-left: 1.5rem;
+  margin: 0 0 1rem;
+}
+
+li {
+  margin-bottom: 0.25rem;
+  line-height: 1.7;
+}
+
+blockquote {
+  margin: 1.5rem 0;
+  padding: 0.75rem 1rem;
+  border-left: 4px solid var(--sl-color-accent);
+  background-color: var(--sl-color-accent-low);
+  border-radius: 0 var(--sl-border-radius) var(--sl-border-radius) 0;
+}
+
+[data-theme='dark'] blockquote {
+  background-color: var(--sl-color-accent-low);
+}
+
+hr {
+  border: none;
+  border-top: 1px solid var(--sl-color-border);
+  margin: 2rem 0;
+}
+
+img {
+  max-width: 100%;
+  height: auto;
+}

package/recipes/starlight/template/server/middleware/vite-dev.ts

@@ -0,0 +1,29 @@
+import { defineEventHandler, fromNodeMiddleware } from 'h3';
+
+let viteHandlerPromise: Promise<ReturnType<typeof fromNodeMiddleware>> | null = null;
+
+export default defineEventHandler(async (event) => {
+  if (!process.dev || !process.env.NITRO_DEV_WORKER_ID) return;
+
+  if (!viteHandlerPromise) {
+    const httpServer = (event.node.req.socket as import('node:net').Socket & {
+      server?: import('node:http').Server;
+    }).server;
+
+    viteHandlerPromise = import('vite')
+      .then(({ createServer }) =>
+        createServer({
+          server: {
+            middlewareMode: true,
+            hmr: httpServer ? { server: httpServer } : true,
+          },
+          appType: 'custom',
+          root: process.cwd(),
+        }),
+      )
+      .then((server) => fromNodeMiddleware(server.middlewares));
+  }
+
+  const viteHandler = await viteHandlerPromise;
+  return viteHandler(event);
+});

package/recipes/starlight/template/server/routes/[...].ts

@@ -0,0 +1,57 @@
+import { defineEventHandler, setResponseHeader, getRequestURL } from 'h3';
+import { createPageHandler } from '@beatzball/litro/runtime/create-page-handler.js';
+import type { LitroRoute } from '@beatzball/litro';
+import { routes, pageModules } from '#litro/page-manifest';
+
+function matchRoute(
+  pathname: string,
+): { route: LitroRoute; params: Record<string, string> } | undefined {
+  for (const route of routes) {
+    if (route.isCatchAll) return { route, params: {} };
+
+    if (!route.isDynamic) {
+      if (pathname === route.path) return { route, params: {} };
+      continue;
+    }
+
+    const regexStr =
+      '^' +
+      route.path
+        .replace(/:([^/]+)\(\.\*\)\*/g, '(?<$1>.+)')
+        .replace(/:([^/?]+)\?/g, '(?<$1>[^/]*)?')
+        .replace(/:([^/]+)/g, '(?<$1>[^/]+)') +
+      '$';
+
+    try {
+      const match = pathname.match(new RegExp(regexStr));
+      if (match) return { route, params: (match.groups ?? {}) as Record<string, string> };
+    } catch {
+      // malformed pattern — skip
+    }
+  }
+  return undefined;
+}
+
+export default defineEventHandler(async (event) => {
+  const pathname = getRequestURL(event).pathname;
+  const result = matchRoute(pathname);
+
+  if (!result) {
+    setResponseHeader(event, 'content-type', 'text/html; charset=utf-8');
+    return `<!DOCTYPE html>
+<html lang="en"><head><meta charset="UTF-8" /><title>404</title></head>
+<body><h1>404 — Not Found</h1><p>No page matched <code>${pathname}</code>.</p></body>
+</html>`;
+  }
+
+  const { route: matched, params } = result;
+  event.context.params = { ...event.context.params, ...params };
+
+  const mod = pageModules[matched.filePath];
+  const handler = createPageHandler({
+    route: matched,
+    routeMeta: (mod?.routeMeta as { title?: string; head?: string } | undefined),
+    pageModule: mod,
+  });
+  return handler(event);
+});

package/recipes/starlight/template/server/starlight.config.js

@@ -0,0 +1,29 @@
+export const siteConfig = {
+  title: '{{projectName}}',
+  description: 'Documentation and blog powered by Litro',
+  logo: null,
+  editUrlBase: null, // e.g. 'https://github.com/you/repo/edit/main'
+  nav: [
+    { label: 'Docs', href: '/docs/getting-started' },
+    { label: 'Blog', href: '/blog' },
+  ],
+  sidebar: [
+    {
+      label: 'Start Here',
+      items: [
+        { label: 'Getting Started', slug: 'getting-started' },
+        { label: 'Installation',    slug: 'installation' },
+        { label: 'Configuration',   slug: 'configuration' },
+      ],
+    },
+    {
+      label: 'Guides',
+      items: [
+        { label: 'Your First Page', slug: 'guides-first-page' },
+        { label: 'Deploying',       slug: 'guides-deploying' },
+      ],
+    },
+  ],
+};
+
+export default siteConfig;

package/recipes/starlight/template/src/components/sl-aside.ts

@@ -0,0 +1,91 @@
+import { LitElement, html, css } from 'lit';
+import { customElement } from 'lit/decorators.js';
+
+type AsideType = 'note' | 'tip' | 'caution' | 'danger';
+
+const ICONS: Record<AsideType, string> = {
+  note:    '&#x2139;&#xFE0F;', // ℹ️
+  tip:     '&#x1F4A1;',        // 💡
+  caution: '&#x26A0;&#xFE0F;', // ⚠️
+  danger:  '&#x1F6A8;',        // 🚨
+};
+
+const LABELS: Record<AsideType, string> = {
+  note:    'Note',
+  tip:     'Tip',
+  caution: 'Caution',
+  danger:  'Danger',
+};
+
+/**
+ * <sl-aside type="tip" title="Custom Title">
+ *   Callout box with an icon and colored left border.
+ *   Slot content is the body.
+ * </sl-aside>
+ */
+@customElement('sl-aside')
+export class SlAside extends LitElement {
+  static override properties = {
+    type: { type: String },
+    title: { type: String },
+  };
+
+  static override styles = css`
+    :host {
+      display: block;
+    }
+
+    .aside {
+      margin: 1.5rem 0;
+      padding: 1rem 1.25rem;
+      border-left: 4px solid;
+      border-radius: 0 var(--sl-border-radius, 0.375rem) var(--sl-border-radius, 0.375rem) 0;
+    }
+
+    .aside.note   { border-color: var(--sl-color-note, #1d4ed8);    background-color: color-mix(in srgb, var(--sl-color-note, #1d4ed8) 8%, transparent); }
+    .aside.tip    { border-color: var(--sl-color-tip, #15803d);     background-color: color-mix(in srgb, var(--sl-color-tip, #15803d) 8%, transparent); }
+    .aside.caution{ border-color: var(--sl-color-caution, #b45309); background-color: color-mix(in srgb, var(--sl-color-caution, #b45309) 8%, transparent); }
+    .aside.danger { border-color: var(--sl-color-danger, #b91c1c);  background-color: color-mix(in srgb, var(--sl-color-danger, #b91c1c) 8%, transparent); }
+
+    .aside-title {
+      display: flex;
+      align-items: center;
+      gap: 0.4em;
+      font-size: var(--sl-text-sm, 0.875rem);
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.06em;
+      margin-bottom: 0.5rem;
+    }
+
+    .aside-title .icon { font-style: normal; }
+
+    .aside.note    .aside-title { color: var(--sl-color-note, #1d4ed8); }
+    .aside.tip     .aside-title { color: var(--sl-color-tip, #15803d); }
+    .aside.caution .aside-title { color: var(--sl-color-caution, #b45309); }
+    .aside.danger  .aside-title { color: var(--sl-color-danger, #b91c1c); }
+
+    ::slotted(p:last-child) { margin-bottom: 0; }
+  `;
+
+  type: AsideType = 'note';
+  title = '';
+
+  override render() {
+    const t = (['note', 'tip', 'caution', 'danger'].includes(this.type)
+      ? this.type
+      : 'note') as AsideType;
+    const label = this.title || LABELS[t];
+    return html`
+      <aside class="aside ${t}">
+        <p class="aside-title">
+          <em class="icon">${ICONS[t]}</em>
+          ${label}
+        </p>
+        <slot></slot>
+      </aside>
+    `;
+  }
+}
+
+export default SlAside;