@beatzball/create-litro 0.1.4 → 0.2.0

package/recipes/starlight/template/content/docs/getting-started.md

@@ -0,0 +1,53 @@
+---
+title: Getting Started
+description: Learn how to set up and run your Litro Starlight docs site.
+sidebar:
+  order: 1
+---
+
+## Welcome
+
+You've just scaffolded a docs and blog site powered by **Litro** — a fullstack web framework that combines Lit web components with Nitro's server engine.
+
+This site is a **static site** (SSG mode). Run `pnpm build` to pre-render every page to HTML, then `pnpm preview` to serve the output locally.
+
+## Prerequisites
+
+You'll need **Node.js 20+** and a package manager (`pnpm`, `npm`, or `yarn`).
+
+## Install Dependencies
+
+```bash
+pnpm install
+```
+
+## Start the Dev Server
+
+```bash
+pnpm dev
+```
+
+The dev server starts on `http://localhost:3030`. Changes to Lit components and Markdown content are reflected immediately.
+
+## Project Structure
+
+```
+my-docs/
+  pages/          Lit page components (filename = route)
+  src/
+    components/   Starlight layout and UI components
+  content/
+    docs/         Documentation Markdown files
+    blog/         Blog post Markdown files
+  server/
+    starlight.config.js   Site title, nav, and sidebar config
+  public/
+    styles/       CSS design tokens (--sl-* variables)
+```
+
+## Next Steps
+
+- Edit `server/starlight.config.js` to update the site title, nav links, and sidebar groups.
+- Add new docs pages to `content/docs/` — each `.md` file becomes a route under `/docs/`.
+- Write blog posts in `content/blog/`.
+- Run `pnpm build` to generate the static site.

package/recipes/starlight/template/content/docs/guides-deploying.md

@@ -0,0 +1,79 @@
+---
+title: Deploying
+description: Deploy your Litro Starlight docs site to any CDN or static hosting platform.
+sidebar:
+  order: 5
+---
+
+## Build
+
+Generate the static HTML output:
+
+```bash
+pnpm build
+```
+
+This runs `litro build` under the hood, which:
+
+1. Scans `pages/` to discover all routes
+2. Calls `generateRoutes()` on each dynamic page to enumerate all paths
+3. Pre-renders every path to a `.html` file in `.output/public/`
+
+## Output
+
+After a successful build, the static site is in `.output/public/`. You can serve this directory from any web server or CDN.
+
+## Platforms
+
+### Vercel
+
+```bash
+# vercel.json
+{
+  "outputDirectory": ".output/public"
+}
+```
+
+Or connect the repository in the Vercel dashboard — Vercel detects the static output automatically.
+
+### Netlify
+
+```toml
+# netlify.toml
+[build]
+  command = "pnpm build"
+  publish = ".output/public"
+```
+
+### Cloudflare Pages
+
+Set the build output directory to `.output/public` in the Cloudflare Pages dashboard.
+
+### GitHub Pages
+
+Add a GitHub Actions workflow:
+
+```yaml
+- name: Build
+  run: pnpm build
+
+- name: Deploy
+  uses: peaceiris/actions-gh-pages@v3
+  with:
+    github_token: GITHUB_TOKEN  # set via repository secrets
+    publish_dir: .output/public
+```
+
+## Custom Domain
+
+Configure the custom domain in your hosting provider's dashboard. No Litro-specific changes are needed — the static output is plain HTML, CSS, and JS.
+
+## Preview Locally
+
+Before deploying, preview the production build locally:
+
+```bash
+pnpm preview
+```
+
+This serves the `.output/` directory using Nitro's static preset server on `http://localhost:3030`.

package/recipes/starlight/template/content/docs/guides-first-page.md

@@ -0,0 +1,64 @@
+---
+title: Your First Page
+description: Create a new docs page and add it to the sidebar navigation.
+sidebar:
+  order: 4
+---
+
+## Create a Markdown File
+
+Add a new `.md` file to `content/docs/`. The filename (without extension) becomes the URL slug.
+
+For example, create `content/docs/my-topic.md`:
+
+```markdown
+---
+title: My Topic
+description: A brief description for SEO and the sidebar.
+---
+
+## Introduction
+
+Write your documentation here using standard Markdown.
+```
+
+## Add It to the Sidebar
+
+Open `server/starlight.config.js` and add an entry to the appropriate sidebar group:
+
+```js
+sidebar: [
+  {
+    label: 'My Section',
+    items: [
+      { label: 'My Topic', slug: 'my-topic' },
+    ],
+  },
+],
+```
+
+The `slug` must match the filename (without `.md`). The page will be available at `/docs/my-topic`.
+
+## Frontmatter Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `title` | `string` | Yes | Page title (shown in sidebar and `<title>`) |
+| `description` | `string` | No | Short summary for SEO |
+| `sidebar.order` | `number` | No | Controls sort order within the sidebar group |
+| `sidebar.label` | `string` | No | Override the label shown in the sidebar |
+
+## Markdown Features
+
+This site supports **GitHub Flavored Markdown (GFM)**, including:
+
+- Tables (like the one above)
+- Fenced code blocks with syntax highlighting
+- Task lists: `- [ ] Todo`
+- Strikethrough: `~~text~~`
+
+Headings (`##`, `###`, `####`) are automatically extracted to build the table of contents shown on the right side of each docs page.
+
+## After Adding a Page
+
+Run `pnpm build` to regenerate the static HTML for all routes, then `pnpm preview` to verify the new page appears in the sidebar and TOC.

package/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/recipes/starlight/template/litro.recipe.json

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

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