first commit

TEMPLATES.md

@@ -0,0 +1,182 @@
+# EmDash Templates
+
+Starter templates for building sites with EmDash CMS. Each template includes a seed file with demo content, so you can see how everything works right away.
+
+## Available Templates
+
+### Blog
+
+A clean, minimal blog with posts, pages, categories, tags, and search.
+
+**Features:**
+
+- Featured post hero on homepage
+- Post grid with reading time estimates
+- Category and tag archives
+- Full-text search
+- RSS feed
+- SEO metadata and JSON-LD
+- Dark/light mode
+
+**Pages:** Homepage, post archive, single post, single page, category archive, tag archive, search results, 404
+
+### Marketing
+
+A landing page template for products and services with modular content blocks.
+
+**Features:**
+
+- Hero, features, testimonials, pricing, and FAQ blocks
+- Contact form with validation
+- Portable Text content editing
+- SEO metadata and JSON-LD
+- Dark/light mode
+
+**Pages:** Homepage, pricing, contact, 404
+
+### Portfolio
+
+A portfolio for showcasing creative work with project pages and tag filtering.
+
+**Features:**
+
+- Project grid with hover effects
+- Tag-based filtering on work page
+- Individual project pages with galleries
+- Contact page
+- RSS feed for new projects
+- SEO metadata and JSON-LD
+- Dark/light mode
+
+**Pages:** Homepage, work listing, single project, about, contact, 404
+
+## Using a Template
+
+Each template has two variants:
+
+- **Node.js** (`templates/blog`, `templates/marketing`, `templates/portfolio`) — uses SQLite and local file storage
+- **Cloudflare** (`templates/blog-cloudflare`, etc.) — uses D1 and R2
+
+### Quick Start
+
+```bash
+# Copy the template you want
+cp -r templates/blog my-site
+cd my-site
+
+# Install dependencies
+pnpm install
+
+# Initialize the database and seed demo content
+pnpm bootstrap
+
+# Start the dev server
+pnpm dev
+```
+
+Open http://localhost:4321 to see your site, and http://localhost:4321/\_emdash/admin for the CMS.
+
+### Template Structure
+
+```
+templates/blog/
+├── src/
+│   ├── components/     # Astro components
+│   ├── layouts/        # Page layouts
+│   ├── pages/          # Route pages
+│   ├── utils/          # Helper functions
+│   └── live.config.ts  # EmDash content loader
+├── seed/
+│   └── seed.json       # Demo content
+├── astro.config.mjs    # Astro + EmDash config
+├── package.json
+└── tsconfig.json
+```
+
+## Contributing
+
+### Cloudflare Variants
+
+The cloudflare variants share most of their code with the base templates. Only these files differ:
+
+- `astro.config.mjs` (cloudflare adapter, D1/R2 storage)
+- `package.json` (different dependencies)
+- `wrangler.jsonc` (cloudflare config)
+
+Everything else is synced from the base template using a script:
+
+```bash
+./scripts/sync-cloudflare-templates.sh
+```
+
+**Run this after making changes** to `src/`, `seed/`, `tsconfig.json`, `emdash-env.d.ts`, or `.gitignore` in any base template. It copies those files to the corresponding cloudflare variant.
+
+The primary Node demo is also synced from the blog template:
+
+```bash
+./scripts/sync-blog-demos.sh
+```
+
+This script does two kinds of sync:
+
+- full template sync for `templates/blog` -> `demos/simple`
+- frontend-only sync (keeping runtime-specific files) for:
+  - `templates/blog-cloudflare` -> `demos/cloudflare`
+  - `templates/blog-cloudflare` -> `demos/preview`
+  - `templates/blog` -> `demos/postgres`
+
+### Taking Screenshots
+
+Template screenshots live in `assets/templates/{template}/latest/` and are used in the README. To update them after making visual changes:
+
+```bash
+# Screenshot all templates (starts each dev server automatically)
+pnpm screenshots
+
+# Screenshot specific templates
+pnpm screenshots blog
+pnpm screenshots blog marketing
+```
+
+The script starts each template's dev server, captures screenshots, then stops the server before moving to the next template.
+
+Page definitions are in `templates/screenshots.json`. Each page is captured at desktop (1440x900) and mobile (390x844) in both light and dark mode at 2x resolution. Screenshots are JPEG at 80% quality.
+
+Output goes to `assets/templates/{template}/{datetime}/` and is copied to `assets/templates/{template}/latest/`. The dated directories are gitignored; only `latest/` is committed. The README references images from `latest/`.
+
+Filenames follow the pattern `{page}-{mode}-{breakpoint}.jpg`, e.g. `homepage-light-desktop.jpg`, `post-dark-mobile.jpg`.
+
+To add pages for a template, edit `templates/screenshots.json`.
+
+### Adding a New Template
+
+1. Create the base template in `templates/{name}/`
+2. Include a seed file at `seed/seed.json` (or configure the path in `package.json` under `emdash.seed`)
+3. Add the `typecheck` script to `package.json`
+4. Create the cloudflare variant in `templates/{name}-cloudflare/` with the appropriate adapter config
+5. Add the template pair to `scripts/sync-cloudflare-templates.sh`
+6. Add the template's pages to `templates/screenshots.json` and run the screenshot script
+7. Update the README template gallery
+
+### Seed Files
+
+Each template includes a seed file with demo content. The seed file format is documented in the CLI (`emdash seed --help`). Key points:
+
+- Use `status: "published"` and include `published_at` for content that should appear on the site
+- Reference media by URL — the seeder downloads and uploads images automatically
+- Use the `taxonomies` object for categories and tags
+- The `emdash.seed` field in `package.json` specifies the seed file location
+
+### Testing Templates
+
+Templates are covered by smoke tests that verify:
+
+- Seed files parse correctly
+- Seeds apply without errors
+- The database passes doctor checks after seeding
+
+Run the smoke tests:
+
+```bash
+pnpm --filter emdash exec vitest run --config vitest.smoke.config.ts
+```