npm - @beatzball/create-litro - Versions diffs - 0.1.4 → 0.2.1 - Mend

@beatzball/create-litro 0.1.4 → 0.2.1

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 (105) hide show

package/recipes/starlight/template/content/blog/welcome.md ADDED Viewed

@@ -0,0 +1,44 @@
+---
+title: Welcome to {{projectName}}
+date: 2026-01-15
+description: Introducing the {{projectName}} docs and blog site, built with Litro and Starlight-inspired components.
+tags:
+  - posts
+  - welcome
+---
+## Hello, World!
+Welcome to **{{projectName}}** — a docs and blog site scaffolded with Litro's Starlight recipe.
+This blog is powered by Litro's content layer. Each `.md` file in `content/blog/` becomes a post, available at `/blog/<slug>`. Write in plain Markdown; the framework handles rendering, tag indexing, and static generation.
+## What's Included
+- **Docs site** at `/docs/` — structured documentation with a sidebar, table of contents, and prev/next navigation
+- **Blog** at `/blog/` — a chronological listing of posts with tag filtering
+- **Dark mode** — a theme toggle in the header that persists to `localStorage`
+- **CSS design tokens** — all colors, fonts, and spacing via `--sl-*` custom properties
+## Writing Posts
+Create a new `.md` file in `content/blog/`:
+```markdown
+---
+title: My Post Title
+date: 2026-02-01
+description: A short summary.
+tags:
+  - posts
+  - my-tag
+---
+Post body here.
+```
+Every post in `content/blog/` inherits the `posts` tag via `blog.11tydata.json`. List any additional tags in the post frontmatter — tag pages are generated automatically at `/blog/tags/<tag>`.
+## Building
+Run `pnpm build` to generate the static HTML for every route, then `pnpm preview` to serve it locally.

package/recipes/starlight/template/content/docs/.11tydata.json ADDED Viewed

	@@ -0,0 +1 @@
1	+ { "section": "docs" }

package/recipes/starlight/template/content/docs/configuration.md ADDED Viewed

@@ -0,0 +1,77 @@
+---
+title: Configuration
+description: Configure your Starlight site — title, navigation, sidebar, and theme.
+sidebar:
+  order: 3
+---
+## Site Config
+All site-wide settings live in `server/starlight.config.js`:
+```js
+export const siteConfig = {
+  title: 'My Docs',
+  description: 'Documentation and blog powered by Litro',
+  logo: null,
+  editUrlBase: null,
+  nav: [...],
+  sidebar: [...],
+};
+```
+### `title`
+The site title shown in the header and used in `<title>` tags.
+### `description`
+A short description used in meta tags.
+### `editUrlBase`
+If set (e.g. `'https://github.com/you/repo/edit/main'`), each doc page shows an "Edit this page" link pointing to the source file on GitHub.
+### `nav`
+Top-level navigation links shown in the header:
+```js
+nav: [
+  { label: 'Docs', href: '/docs/getting-started' },
+  { label: 'Blog', href: '/blog' },
+],
+```
+### `sidebar`
+Sidebar groups, each with a label and array of items. Each item has a `label` and a `slug` (the filename without `.md` under `content/docs/`):
+```js
+sidebar: [
+  {
+    label: 'Start Here',
+    items: [
+      { label: 'Getting Started', slug: 'getting-started' },
+      { label: 'Installation',    slug: 'installation' },
+    ],
+  },
+],
+```
+## CSS Design Tokens
+The visual theme is controlled by CSS custom properties in `public/styles/starlight.css`. Override any `--sl-*` variable to customize colors, fonts, and spacing:
+```css
+:root {
+  --sl-color-accent: #7c3aed;    /* primary accent color */
+  --sl-font-sans: ui-sans-serif, system-ui, sans-serif;
+}
+```
+Dark mode tokens are under `[data-theme='dark'] { ... }`.
+## Dark / Light Mode
+The theme toggle button in the header reads and writes `localStorage.getItem('sl-theme')`. A FOUC-prevention inline script (injected via `routeMeta.head`) sets `data-theme` on `<html>` before first paint.

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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/e2e/index.spec.ts ADDED Viewed

@@ -0,0 +1,32 @@
+import { test, expect } from '@playwright/test';
+const PRERENDERED_ROUTES = [
+  '/',
+  '/docs/getting-started',
+  '/docs/installation',
+  '/docs/configuration',
+  '/docs/guides-first-page',
+  '/docs/guides-deploying',
+  '/blog',
+  '/blog/welcome',
+  '/blog/release-notes',
+];
+test('home renders page-home component', async ({ page }) => {
+  await page.goto('/');
+  await page.waitForSelector('page-home');
+  await expect(page.locator('page-home')).toBeVisible();
+});
+test('/docs/getting-started renders', async ({ page }) => {
+  await page.goto('/docs/getting-started');
+  await page.waitForSelector('page-docs-slug');
+  await expect(page.locator('page-docs-slug')).toBeVisible();
+});
+test('all prerendered routes return 200', async ({ request }) => {
+  for (const route of PRERENDERED_ROUTES) {
+    const response = await request.get(route);
+    expect(response.status(), `Expected 200 for ${route}`).toBe(200);
+  }
+});

package/recipes/starlight/template/litro.recipe.json ADDED Viewed

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

package/recipes/starlight/template/nitro.config.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -0,0 +1,28 @@
+{
+  "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",
+    "test:e2e": "playwright test"
+  },
+  "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",
+    "@playwright/test": "^1.48.0"
+  }
+}

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

@@ -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;