@beatzball/create-litro 0.1.3 → 0.2.0

package/dist/recipes/starlight/template/content/docs/installation.md

@@ -0,0 +1,54 @@
+---
+title: Installation
+description: Install dependencies and configure your Litro Starlight project.
+sidebar:
+  order: 2
+---
+
+## Package Manager
+
+This project uses **pnpm** by default. You can also use `npm` or `yarn` — just replace `pnpm` in the commands below.
+
+## Install
+
+From the project root, run:
+
+```bash
+pnpm install
+```
+
+This installs all dependencies listed in `package.json`, including:
+
+- **`@beatzball/litro`** — the Litro framework (pages plugin, SSR/SSG, content layer)
+- **`lit`** — Lit web components library
+- **`@lit-labs/ssr`** — server-side rendering via Declarative Shadow DOM
+- **`@lit-labs/ssr-client`** — hydration support script
+
+## TypeScript
+
+The project ships with `tsconfig.json` preconfigured for Lit decorators:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false
+  }
+}
+```
+
+These two settings are required for Lit's `@customElement`, `@state`, and `@property` decorators to work correctly with TypeScript's decorator transform.
+
+## Environment
+
+No environment variables are required for SSG mode. If you add API routes later, create a `.env` file at the project root.
+
+## Verify
+
+After installing, start the dev server:
+
+```bash
+pnpm dev
+```
+
+Navigate to `http://localhost:3030`. You should see the splash page with the sidebar navigation.

package/dist/recipes/starlight/template/litro.recipe.json

@@ -0,0 +1,7 @@
+{
+  "recipe": "starlight",
+  "version": "{{recipeVersion}}",
+  "mode": "ssg",
+  "contentDir": "content",
+  "options": {}
+}

package/dist/recipes/starlight/template/nitro.config.ts

@@ -0,0 +1,57 @@
+import { defineNitroConfig } from 'nitropack/config';
+import type { Nitro } from 'nitropack';
+import { resolve } from 'node:path';
+import { ssgPreset } from '@beatzball/litro/config';
+import pagesPlugin from '@beatzball/litro/plugins';
+import ssgPlugin from '@beatzball/litro/plugins/ssg';
+import contentPlugin from '@beatzball/litro/content/plugin';
+
+export default defineNitroConfig({
+  ...ssgPreset(),
+
+  srcDir: 'server',
+
+  publicAssets: [
+    { dir: '../dist/client', baseURL: '/_litro/', maxAge: 31536000 },
+    { dir: '../public',      baseURL: '/',        maxAge: 0 },
+    { dir: '../content',     baseURL: '/content/', maxAge: 86400 },
+  ],
+
+  externals: { inline: ['@lit-labs/ssr', '@lit-labs/ssr-client'] },
+
+  esbuild: {
+    options: {
+      tsconfigRaw: {
+        compilerOptions: {
+          experimentalDecorators: true,
+          useDefineForClassFields: false,
+        },
+      },
+    },
+  },
+
+  ignore: ['**/middleware/vite-dev.ts'],
+  handlers: [
+    {
+      middleware: true,
+      handler: resolve('./server/middleware/vite-dev.ts'),
+      env: 'dev',
+    },
+  ],
+
+  hooks: {
+    'build:before': async (nitro: Nitro) => {
+      await contentPlugin(nitro);
+      await pagesPlugin(nitro);
+      await ssgPlugin(nitro);
+    },
+  },
+
+  compatibilityDate: '2025-01-01',
+
+  routeRules: {
+    '/_litro/**': {
+      headers: { 'cache-control': 'public, max-age=31536000, immutable' },
+    },
+  },
+});

package/dist/recipes/starlight/template/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#litro/page-manifest": "./server/stubs/page-manifest.ts"
+  },
+  "scripts": {
+    "dev": "litro dev",
+    "build": "litro build",
+    "preview": "litro preview",
+    "generate": "litro generate"
+  },
+  "dependencies": {
+    "@beatzball/litro": "latest",
+    "lit": "^3.2.1",
+    "@lit-labs/ssr": "^3.3.0",
+    "@lit-labs/ssr-client": "^1.1.7",
+    "h3": "^1.13.0"
+  },
+  "devDependencies": {
+    "nitropack": "^2.13.1",
+    "vite": "^5.4.11",
+    "typescript": "^5.7.3"
+  }
+}

package/dist/recipes/starlight/template/pages/blog/[slug].ts

@@ -0,0 +1,125 @@
+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';
+import { formatDate, isoDate } from '../../src/date-utils.js';
+
+// Register components used in render()
+import '../../src/components/starlight-header.js';
+
+export interface BlogPostData {
+  post: Post;
+  body: string;
+  toc: Array<{ depth: number; text: string; slug: string }>;
+  siteTitle: string;
+  nav: typeof siteConfig.nav;
+}
+
+export const pageData = definePageData(async (event) => {
+  const slug = event.context.params?.slug ?? '';
+
+  // Content URLs are /content/blog/<slug> (contentDir = 'content')
+  const posts = await getPosts();
+  const post = posts.find(p => p.url === `/content/blog/${slug}`);
+
+  if (!post) {
+    throw createError({ statusCode: 404, message: `Post not found: ${slug}` });
+  }
+
+  const toc = extractHeadings(post.rawBody);
+  const body = addHeadingIds(post.body);
+
+  return {
+    post,
+    body,
+    toc,
+    siteTitle: siteConfig.title,
+    nav: siteConfig.nav,
+  } satisfies BlogPostData;
+});
+
+export async function generateRoutes(): Promise<string[]> {
+  const posts = await getPosts();
+  return posts
+    .filter(p => p.url.startsWith('/content/blog/'))
+    .map(p => '/blog' + p.url.slice('/content/blog'.length));
+}
+
+export const routeMeta = {
+  head: starlightHead,
+  title: 'Blog — {{projectName}}',
+};
+
+@customElement('page-blog-slug')
+export class BlogPostPage extends LitroPage {
+  override render() {
+    const data = this.serverData as BlogPostData | null;
+    if (!data?.post) return html`<p>Loading&hellip;</p>`;
+
+    const { post, body, siteTitle, nav } = data;
+    const blogSlug = post.url.slice('/content/blog/'.length);
+
+    return html`
+      <div style="min-height:100vh;display:flex;flex-direction:column;">
+        <starlight-header
+          siteTitle="${siteTitle}"
+          .nav="${nav}"
+          currentPath="/blog/${blogSlug}"
+        ></starlight-header>
+        <main style="
+          flex:1;
+          max-width:52rem;
+          margin:0 auto;
+          padding:var(--sl-content-pad-y,2rem) var(--sl-content-pad-x,1.5rem);
+          width:100%;
+        ">
+          <article>
+            <header style="margin-bottom:2rem;">
+              <h1 style="font-size:var(--sl-text-4xl);font-weight:700;margin:0 0 0.75rem;line-height:1.15;">
+                ${post.title}
+              </h1>
+              <time
+                datetime="${isoDate(post.date)}"
+                style="font-size:var(--sl-text-sm);color:var(--sl-color-gray-4);"
+              >${formatDate(post.date)}</time>
+              ${post.tags.filter(t => t !== 'posts').length > 0 ? html`
+                <div style="display:flex;gap:0.4rem;flex-wrap:wrap;margin-top:0.75rem;">
+                  ${post.tags.filter(t => t !== 'posts').map(tag => html`
+                    <a href="/blog/tags/${tag}" style="
+                      display:inline-block;
+                      padding:0.15em 0.55em;
+                      font-size:var(--sl-text-xs);
+                      border-radius:9999px;
+                      background:var(--sl-color-accent-low);
+                      color:var(--sl-color-accent-high,#5b21b6);
+                      text-decoration:none;
+                      font-weight:600;
+                    ">#${tag}</a>
+                  `)}
+                </div>
+              ` : ''}
+            </header>
+            <!-- unsafeHTML renders the Markdown-generated HTML directly.
+                 The content directory is trusted-author-only; do not place
+                 user-submitted or untrusted content here without sanitizing. -->
+            ${unsafeHTML(body)}
+          </article>
+          <footer style="margin-top:3rem;padding-top:1.5rem;border-top:1px solid var(--sl-color-border);">
+            <a href="/blog" style="font-size:var(--sl-text-sm);color:var(--sl-color-accent);text-decoration:none;">
+              ← Back to Blog
+            </a>
+          </footer>
+        </main>
+      </div>
+    `;
+  }
+}
+
+export default BlogPostPage;

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

@@ -0,0 +1,114 @@
+import { html } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import { LitroPage } from '@beatzball/litro/runtime';
+import { definePageData } from '@beatzball/litro';
+import type { Post } from 'litro:content';
+import { getPosts } from 'litro:content';
+import { siteConfig } from '../../server/starlight.config.js';
+import { starlightHead } from '../../src/route-meta.js';
+import { formatDate, isoDate } from '../../src/date-utils.js';
+
+// Register components used in render()
+import '../../src/components/starlight-header.js';
+
+export interface BlogIndexData {
+  posts: Post[];
+  siteTitle: string;
+  nav: typeof siteConfig.nav;
+}
+
+export const pageData = definePageData(async (_event) => {
+  const all = await getPosts();
+  // Filter to only blog posts (URL prefix from contentDir='content')
+  const posts = all.filter(p => p.url.startsWith('/content/blog/'));
+  return {
+    posts,
+    siteTitle: siteConfig.title,
+    nav: siteConfig.nav,
+  } satisfies BlogIndexData;
+});
+
+export const routeMeta = {
+  head: starlightHead,
+  title: 'Blog — {{projectName}}',
+};
+
+@customElement('page-blog')
+export class BlogIndexPage extends LitroPage {
+  override render() {
+    const data = this.serverData as BlogIndexData | null;
+    const { posts = [], siteTitle = '{{projectName}}', nav = [] } = data ?? {};
+
+    return html`
+      <div style="min-height:100vh;display:flex;flex-direction:column;">
+        <starlight-header
+          siteTitle="${siteTitle}"
+          .nav="${nav}"
+          currentPath="/blog"
+        ></starlight-header>
+        <main style="
+          flex:1;
+          max-width:56rem;
+          margin:0 auto;
+          padding:var(--sl-content-pad-y,2rem) var(--sl-content-pad-x,1.5rem);
+          width:100%;
+        ">
+          <h1 style="
+            font-size:var(--sl-text-4xl);
+            font-weight:700;
+            margin:0 0 2rem;
+          ">Blog</h1>
+
+          ${posts.length === 0 ? html`
+            <p style="color:var(--sl-color-gray-4);">No posts yet.</p>
+          ` : html`
+            <ul style="list-style:none;padding:0;margin:0;display:flex;flex-direction:column;gap:2rem;">
+              ${posts.map(post => {
+                const blogSlug = post.url.slice('/content/blog/'.length);
+                return html`
+                  <li style="border-bottom:1px solid var(--sl-color-border);padding-bottom:2rem;">
+                    <a href="/blog/${blogSlug}" style="
+                      display:block;
+                      font-size:var(--sl-text-2xl);
+                      font-weight:600;
+                      color:var(--sl-color-text);
+                      text-decoration:none;
+                      margin-bottom:0.4rem;
+                    ">${post.title}</a>
+                    <time
+                      datetime="${isoDate(post.date)}"
+                      style="font-size:var(--sl-text-sm);color:var(--sl-color-gray-4);"
+                    >${formatDate(post.date)}</time>
+                    ${post.description ? html`
+                      <p style="margin:0.5rem 0 0.75rem;color:var(--sl-color-gray-5);line-height:1.6;">
+                        ${post.description}
+                      </p>
+                    ` : ''}
+                    ${post.tags.filter(t => t !== 'posts').length > 0 ? html`
+                      <div style="display:flex;gap:0.4rem;flex-wrap:wrap;margin-top:0.5rem;">
+                        ${post.tags.filter(t => t !== 'posts').map(tag => html`
+                          <a href="/blog/tags/${tag}" style="
+                            display:inline-block;
+                            padding:0.15em 0.55em;
+                            font-size:var(--sl-text-xs);
+                            border-radius:9999px;
+                            background:var(--sl-color-accent-low);
+                            color:var(--sl-color-accent-high,#5b21b6);
+                            text-decoration:none;
+                            font-weight:600;
+                          ">#${tag}</a>
+                        `)}
+                      </div>
+                    ` : ''}
+                  </li>
+                `;
+              })}
+            </ul>
+          `}
+        </main>
+      </div>
+    `;
+  }
+}
+
+export default BlogIndexPage;

package/dist/recipes/starlight/template/pages/blog/tags/[tag].ts

@@ -0,0 +1,110 @@
+import { html } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import { LitroPage } from '@beatzball/litro/runtime';
+import { definePageData } from '@beatzball/litro';
+import type { Post } from 'litro:content';
+import { getPosts } from 'litro:content';
+import { siteConfig } from '../../../server/starlight.config.js';
+import { starlightHead } from '../../../src/route-meta.js';
+import { formatDate, isoDate } from '../../../src/date-utils.js';
+
+// Register components used in render()
+import '../../../src/components/starlight-header.js';
+
+export interface TagPageData {
+  tag: string;
+  posts: Post[];
+  siteTitle: string;
+  nav: typeof siteConfig.nav;
+}
+
+export const pageData = definePageData(async (event) => {
+  const tag = event.context.params?.tag ?? '';
+  const all = await getPosts({ tag });
+  // Filter to only blog posts (docs might have unexpected tags)
+  const posts = all.filter(p => p.url.startsWith('/content/blog/'));
+  return {
+    tag,
+    posts,
+    siteTitle: siteConfig.title,
+    nav: siteConfig.nav,
+  } satisfies TagPageData;
+});
+
+export async function generateRoutes(): Promise<string[]> {
+  const all = await getPosts();
+  const blogPosts = all.filter(p => p.url.startsWith('/content/blog/'));
+  const tags = [...new Set(blogPosts.flatMap(p => p.tags))].sort();
+  return tags.map(tag => `/blog/tags/${tag}`);
+}
+
+export const routeMeta = {
+  head: starlightHead,
+  title: 'Tags — {{projectName}}',
+};
+
+@customElement('page-blog-tags-tag')
+export class TagPage extends LitroPage {
+  override render() {
+    const data = this.serverData as TagPageData | null;
+    const { tag = '', posts = [], siteTitle = '{{projectName}}', nav = [] } = data ?? {};
+
+    return html`
+      <div style="min-height:100vh;display:flex;flex-direction:column;">
+        <starlight-header
+          siteTitle="${siteTitle}"
+          .nav="${nav}"
+          currentPath="/blog/tags/${tag}"
+        ></starlight-header>
+        <main style="
+          flex:1;
+          max-width:56rem;
+          margin:0 auto;
+          padding:var(--sl-content-pad-y,2rem) var(--sl-content-pad-x,1.5rem);
+          width:100%;
+        ">
+          <h1 style="font-size:var(--sl-text-4xl);font-weight:700;margin:0 0 2rem;">
+            Posts tagged: <span style="color:var(--sl-color-accent);">#${tag}</span>
+          </h1>
+
+          ${posts.length === 0 ? html`
+            <p style="color:var(--sl-color-gray-4);">No posts found for this tag.</p>
+          ` : html`
+            <ul style="list-style:none;padding:0;margin:0;display:flex;flex-direction:column;gap:1.5rem;">
+              ${posts.map(post => {
+                const blogSlug = post.url.slice('/content/blog/'.length);
+                return html`
+                  <li style="border-bottom:1px solid var(--sl-color-border);padding-bottom:1.5rem;">
+                    <a href="/blog/${blogSlug}" style="
+                      display:block;
+                      font-size:var(--sl-text-xl);
+                      font-weight:600;
+                      color:var(--sl-color-text);
+                      text-decoration:none;
+                      margin-bottom:0.3rem;
+                    ">${post.title}</a>
+                    <time
+                      datetime="${isoDate(post.date)}"
+                      style="font-size:var(--sl-text-sm);color:var(--sl-color-gray-4);"
+                    >${formatDate(post.date)}</time>
+                    ${post.description ? html`
+                      <p style="margin:0.4rem 0 0;color:var(--sl-color-gray-5);">${post.description}</p>
+                    ` : ''}
+                  </li>
+                `;
+              })}
+            </ul>
+          `}
+
+          <p style="margin-top:2rem;">
+            <a href="/blog" style="font-size:var(--sl-text-sm);color:var(--sl-color-accent);text-decoration:none;">
+              ← All Posts
+            </a>
+          </p>
+        </main>
+      </div>
+    `;
+  }
+}
+
+export default TagPage;

package/dist/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;