uniweb 0.2.39 → 0.2.41

package/README.md

@@ -1,24 +1,39 @@
 # uniweb
 
-Create a well-structured Vite + React site with content/code separation, file-based routing, localization, and structured content—out of the box. The architecture scales to dynamic content management and collaborative visual editing when you need it.
+A component content architecture for React. Build sites where content authors and component developers can't break each other's work—and scale from local files to visual editing without rewrites.
 
-## Quick Start
+Create well-structured Vite + React projects with file-based routing, localization, and clean content/code separation out of the box.
 
-Create a new Uniweb project:
+## Quick Start
 
 ```bash
-npx uniweb@latest create my-project
-cd my-project
+npx uniweb@latest create my-site --template marketing
+cd my-site
 pnpm install
 pnpm dev
 ```
 
-You get a workspace with two packages:
+The `marketing` template includes real components (Hero, Features, Pricing, Testimonials, FAQ, and more) with sample content—a working site you can explore and modify.
+
+**Other templates:**
+
+```bash
+# Academic site (researcher portfolios, lab pages)
+npx uniweb@latest create my-site --template academic
+
+# Documentation site
+npx uniweb@latest create my-site --template docs
+
+# Minimal starter (build from scratch)
+npx uniweb@latest create my-site
+```
+
+Every project is a workspace with two packages:
 
 - **`site/`** — Content, pages, entry point
-- **`foundation/`** — Your React components
+- **`foundation/`** — React components
 
-Content authors work in markdown. Component authors work in React. Neither can break the other's work, and component updates flow to every site using them.
+Content authors work in markdown. Component authors work in React. Neither can break the other's work.
 
 ## What You Get
 
@@ -30,8 +45,6 @@ my-project/
 │   │       ├── page.yml      # Page metadata
 │   │       └── 1-hero.md     # Section content
 │   ├── locales/              # i18n (hash-based translations)
-│   │   ├── manifest.json     # Auto-extracted strings
-│   │   └── es.json           # Spanish translations
 │   ├── main.js               # Entry point (~6 lines)
 │   ├── vite.config.js        # 3-line config
 │   └── public/               # Static assets
@@ -84,13 +97,13 @@ Components receive validated, localized data. Natural content stays in markdown;
 
 ```jsx
 export function Hero({ content, params }) {
-  const { title } = content.main.header;
-  const { paragraphs, links } = content.main.body;
-  const { theme = "light" } = params;
+  const { title } = content.main.header
+  const { paragraphs, links } = content.main.body
+  const { theme = 'light' } = params
 
   return (
     <section
-      className={`py-20 text-center ${theme === "dark" ? "bg-gray-900 text-white" : ""}`}
+      className={`py-20 text-center ${theme === 'dark' ? 'bg-gray-900 text-white' : ''}`}
     >
       <h1 className="text-4xl font-bold">{title}</h1>
       <p className="text-xl text-gray-600">{paragraphs[0]}</p>
@@ -103,23 +116,45 @@ export function Hero({ content, params }) {
         </a>
       )}
     </section>
-  );
+  )
 }
 ```
 
-Standard React. Standard Tailwind. The `{ content, params }` interface is only for _exposed_ components—the ones content creators select in markdown frontmatter. Internal components (the majority of your codebase) use regular React props.
+Standard React. Standard Tailwind. The `{ content, params }` interface is only for _exposed_ components—the ones content creators select in markdown frontmatter. Internal components use regular React props.
+
+## Foundations Are Portable
+
+The `foundation/` folder ships with your project as a convenience, but a foundation is a self-contained artifact with no dependency on any specific site. Sites reference foundations by configuration, not by folder proximity.
+
+**Three ways to use a foundation:**
+
+| Mode             | How it works                       | Best for                                           |
+| ---------------- | ---------------------------------- | -------------------------------------------------- |
+| **Local folder** | Foundation lives in your workspace | Developing site and components together            |
+| **npm package**  | `pnpm add @acme/foundation`        | Distributing via standard package tooling          |
+| **Runtime link** | Foundation loads from a URL        | Independent release cycles, platform-managed sites |
+
+You can delete the `foundation/` folder entirely and point your site at a published foundation. Or develop a foundation locally, then publish it for other sites to consume. The site doesn't care where its components come from.
+
+**This enables two development patterns:**
+
+_Site-first_ — You're building a website. The foundation is your component library, co-developed with the site. This is the common case.
 
-No framework to learn. Foundations are purpose-built component systems designed for a specific domain (marketing, documentation, learning, etc.). Sites are Vite apps that load content from markdown files.
+_Foundation-first_ — You're building a component system. The site is a test harness with sample content. The real sites live elsewhere—other repositories, other teams, or managed on [uniweb.app](https://uniweb.app). The `multi` template supports this workflow with multiple test sites exercising a shared foundation.
 
 ## The Bigger Picture
 
 The structure you start with scales without rewrites:
 
-1. **Single project** — One site, one component library. Most projects stay here.
-2. **Multi-site** — One foundation powers multiple sites. Release it once, updates propagate automatically.
-3. **Full platform** — [uniweb.app](https://uniweb.app) adds visual editing, live content management, and team collaboration. Your foundation plugs in and its components become native to the editor.
+1. **Single project** — One site, one foundation. Develop and deploy together. Most projects stay here.
 
-Start with local markdown files deployed anywhere. Connect to [uniweb.app](https://uniweb.app) when you're ready for dynamic content and team collaboration.
+2. **Published foundation** — Release your foundation as an npm package or to [uniweb.app](https://uniweb.app). Other sites can use it without copying code.
+
+3. **Multiple sites** — Several sites share one foundation. Update components once, every site benefits.
+
+4. **Platform-managed sites** — Sites built on [uniweb.app](https://uniweb.app) with visual editing tools can use your foundation. You develop components locally; content teams work in the browser.
+
+Start with local files deployed anywhere. The same foundation works across all these scenarios.
 
 ---
 
@@ -250,123 +285,58 @@ build:
   prerender: true
 ```
 
-Or use the `--prerender` flag to force it on (or `--no-prerender` to skip it). This is useful for:
+Or use the `--prerender` flag. This gives you:
 
 - **SEO**: Search engines see fully rendered content immediately
-- **Performance**: First contentful paint is instant (no JavaScript required)
+- **Performance**: First contentful paint is instant
 - **Hosting**: Deploy to any static host (GitHub Pages, Netlify, S3, etc.)
 
-**How it works:**
-
-1. The site build runs first, generating the JavaScript bundle and `site-content.json`
-2. The prerenderer loads the foundation and site content in Node.js
-3. Each page is rendered to HTML using React's `renderToString()`
-4. The HTML is injected into the shell with the site content embedded
-
-**Hydration:**
-
-The pre-rendered HTML includes a `<script id="__SITE_CONTENT__">` tag with the full site data. When the page loads in the browser:
-
-1. The static HTML displays immediately (no flash of loading state)
-2. React hydrates the existing DOM instead of replacing it
-3. The site becomes fully interactive with client-side routing
-
-**Usage:**
-
-```bash
-# From site directory (with build.prerender: true in site.yml)
-cd site
-pnpm build
-
-# Or force pre-rendering via CLI flag
-cd site && uniweb build --prerender
-```
+The pre-rendered HTML includes embedded site content. When the page loads, React hydrates the existing DOM—no flash of loading state, then full client-side interactivity.
 
 ## Built-in Templates
 
 ### Single (Default)
 
-A minimal workspace with a site and foundation as sibling packages. This is the recommended starting point.
+A minimal workspace with a site and foundation as sibling packages. The recommended starting point.
 
 ```
 my-project/
-├── package.json              # Workspace root (npm + pnpm compatible)
-├── pnpm-workspace.yaml       # Pre-configured for evolution (see below)
-├── CLAUDE.md                 # AI assistant instructions
-│
-├── site/                     # Site package (content + entry)
+├── package.json              # Workspace root
+├── pnpm-workspace.yaml
+├── site/
 │   ├── package.json
-│   ├── vite.config.js        # 3-line config
-│   ├── index.html
-│   ├── site.yml              # Site configuration (foundation, title, i18n)
-│   ├── main.js               # Entry point (~6 lines)
-│   ├── pages/                # Content pages (file-based routing)
-│   │   └── home/
-│   │       ├── page.yml
-│   │       └── 1-hero.md
-│   └── public/               # Static assets
-│
-└── foundation/               # Foundation package (components)
+│   ├── vite.config.js
+│   ├── site.yml
+│   ├── main.js
+│   └── pages/
+└── foundation/
     ├── package.json
-    ├── vite.config.js        # 3-line config
-    └── src/
-        ├── styles.css        # Tailwind CSS v4
-        ├── meta.js           # Foundation metadata
-        ├── exports.js        # (optional) Custom Layout, props
-        └── components/
-            └── Section/
-                ├── index.jsx
-                └── meta.js
+    ├── vite.config.js
+    └── src/components/
 ```
 
-**Key characteristics:**
-
-- **Convention-compliant** — Each package has its own `src/`
-- **Clear dep boundaries** — Component libs → `foundation/package.json`, runtime → `site/package.json`
-- **Zero extraction** — `foundation/` is already a complete, publishable package
-- **Scales naturally** — Rename to `sites/marketing/` and `foundations/marketing/` when needed
-
 ### Multi
 
-A monorepo for multi-site or multi-foundation development.
+A monorepo for foundation development or multi-site projects.
 
 ```
 my-workspace/
-├── package.json              # Workspace root (npm + pnpm compatible)
-├── pnpm-workspace.yaml       # Same config as single template
-├── CLAUDE.md                 # AI assistant instructions
-│
 ├── sites/
-│   ├── marketing/            # Main marketing site
-│   │   ├── package.json
-│   │   ├── vite.config.js    # 3-line config
-│   │   ├── site.yml
-│   │   ├── main.js           # Entry point (~6 lines)
-│   │   └── pages/
-│   └── docs/                 # Documentation site
-│
+│   ├── marketing/            # Main site or test site
+│   └── docs/                 # Additional site
 └── foundations/
-    ├── marketing/            # Marketing foundation
-    │   ├── package.json
-    │   ├── vite.config.js    # 3-line config
-    │   └── src/components/
-    └── documentation/        # Documentation foundation
+    ├── marketing/            # Primary foundation
+    └── documentation/        # Additional foundation
 ```
 
-Use this when you need:
-
-- Multiple sites sharing foundations
-- Multiple foundations for different purposes
-- A testing site for foundation development
+Use this when you need multiple sites sharing foundations, multiple foundations for different purposes, or test sites for foundation development.
 
 ## Official Templates
 
-Feature-rich templates that demonstrate what's possible with Uniweb. These include real components, sample content, and production-ready structure.
+Feature-rich templates with real components and sample content.
 
 ### Marketing
 
-A complete marketing site with landing page components:
-
 ```bash
 uniweb create my-site --template marketing
 ```
@@ -383,8 +353,6 @@ uniweb create my-site --template marketing --variant tailwind3
 
 ### Academic
 
-A professional academic site for researchers, labs, and departments:
-
 ```bash
 uniweb create my-site --template academic
 ```
@@ -395,8 +363,6 @@ Perfect for researcher portfolios, lab websites, and academic department sites.
 
 ### Docs
 
-A documentation site with navigation levels:
-
 ```bash
 uniweb create my-site --template docs
 ```
@@ -407,7 +373,7 @@ Perfect for technical documentation, guides, and API references.
 
 ## External Templates
 
-You can use templates from npm or GitHub:
+Use templates from npm or GitHub:
 
 ```bash
 # npm package
@@ -420,8 +386,6 @@ uniweb create my-site --template github:user/repo
 uniweb create my-site --template github:user/repo#v1.0.0
 ```
 
-External templates must follow the same structure as official templates. See [`@uniweb/templates`](https://github.com/uniweb/templates) for the template format specification.
-
 ## Dependency Management
 
 Each package manages its own dependencies:
@@ -452,14 +416,14 @@ cd foundation && pnpm add embla-carousel
 The `defineSiteConfig()` function handles all Vite configuration for sites:
 
 ```javascript
-import { defineSiteConfig } from "@uniweb/build/site";
+import { defineSiteConfig } from '@uniweb/build/site'
 
 export default defineSiteConfig({
   // All options are optional
   tailwind: true, // Enable Tailwind CSS v4 (default: true)
   plugins: [], // Additional Vite plugins
   // ...any other Vite config options
-});
+})
 ```
 
 ### Foundation Configuration
@@ -467,11 +431,11 @@ export default defineSiteConfig({
 The `defineFoundationConfig()` function handles all Vite configuration for foundations:
 
 ```javascript
-import { defineFoundationConfig } from "@uniweb/build";
+import { defineFoundationConfig } from '@uniweb/build'
 
 export default defineFoundationConfig({
   // All options are optional - entry is auto-generated
-  fileName: "foundation", // Output file name
+  fileName: 'foundation', // Output file name
   externals: [], // Additional packages to externalize
   includeDefaultExternals: true, // Include react, @uniweb/core, etc.
   tailwind: true, // Enable Tailwind CSS v4 Vite plugin
@@ -479,7 +443,7 @@ export default defineFoundationConfig({
   plugins: [], // Additional Vite plugins
   build: {}, // Additional Vite build options
   // ...any other Vite config options
-});
+})
 ```
 
 For Tailwind CSS v3 projects, set `tailwind: false` and use PostCSS:
@@ -487,7 +451,7 @@ For Tailwind CSS v3 projects, set `tailwind: false` and use PostCSS:
 ```javascript
 export default defineFoundationConfig({
   tailwind: false, // Uses PostCSS instead of Vite plugin
-});
+})
 ```
 
 ## Foundation Build Process
@@ -520,62 +484,40 @@ Both templates use the same unified workspace configuration:
 ```yaml
 # pnpm-workspace.yaml
 packages:
-  - "site"
-  - "foundation"
-  - "sites/*"
-  - "foundations/*"
+  - 'site'
+  - 'foundation'
+  - 'sites/*'
+  - 'foundations/*'
 ```
 
+Also set in `package.json` for npm compatibility.
+
 ```json
-// package.json (workspaces field for npm compatibility)
 {
   "workspaces": ["site", "foundation", "sites/*", "foundations/*"]
 }
 ```
 
-This means **no config changes when evolving your project**.
-
-## Evolving Your Project
-
-The workspace is pre-configured for growth. Choose your path:
-
-**Add alongside existing structure:**
+This means no config changes when evolving from single to multi-site.
 
-```bash
-# Keep site/ and foundation/, add more in sites/ and foundations/
-mkdir -p sites/docs
-mkdir -p foundations/documentation
-```
+## Releasing a Foundation
 
-**Or migrate to multi-site structure:**
+Publish your foundation to npm:
 
 ```bash
-# Move and rename by purpose
-mv site sites/marketing
-mv foundation foundations/marketing
-
-# Update package names and workspace dependencies in package.json files
+cd foundation
+npm publish
 ```
 
-Both patterns work simultaneously—evolve gradually as needed.
-
-## Releasing a Foundation
-
-Publish your foundation to [uniweb.app](https://uniweb.app) to make it available for your sites:
+Or to [uniweb.app](https://uniweb.app) for use with platform-managed sites:
 
 ```bash
 uniweb login          # First time only
 uniweb build
-uniweb publish        # Publishes the foundation in the current directory
+uniweb publish
 ```
 
-Each release creates a new version. Sites link to foundations at runtime and control their own update strategy—automatic, minor-only, patch-only, or pinned to a specific version. You own your foundations and license them to sites—yours or your clients'.
-
-You can also publish to npm:
-
-```bash
-npm publish
-```
+Sites control their own update strategy—automatic, minor-only, patch-only, or pinned to a specific version.
 
 ## FAQ
 
@@ -585,19 +527,23 @@ MDX blends markdown and JSX—content authors write code. Uniweb keeps them sepa
 
 **How is this different from Astro?**
 
-Astro is a static site generator. Uniweb is a content architecture that works with any deployment (static, SSR, or platform-managed). The Foundation model means components are reusable across sites and ready for visual editing.
+Astro is a static site generator. Uniweb is a component content architecture that works with any deployment (static, SSR, or platform-managed). The foundation model means components are portable across sites and ready for integration with visual editors.
 
 **Do I need uniweb.app?**
 
 No. Local markdown files work great for developer-managed sites. The platform adds dynamic content, visual editing, and team collaboration when you need it.
 
+**Can I use an existing component library?**
+
+Yes. Foundations are standard React. Import any library into your foundation components. The `{ content, params }` interface only applies to exposed components—internal components use regular props.
+
 **Is this SEO-friendly?**
 
-Yes. Content is pre-embedded in the initial HTML—no fetch waterfalls, no layout shifts, instant interaction. Meta tags are generated per page for proper social sharing previews. SSG and SSR are also supported.
+Yes. Content is pre-embedded in the initial HTML—no fetch waterfalls, no layout shifts. Meta tags are generated per page. SSG is supported by default.
 
 **What about dynamic routes?**
 
-Pages can define data sources that auto-generate subroutes. A `/blog` page can have an index (listing) and a `[slug]` template that renders each post. No manual folders for every entry.
+Pages can define data sources that auto-generate subroutes. A `/blog` page can have an index and a `[slug]` template that renders each post.
 
 ## Related Packages
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.2.39",
+  "version": "0.2.41",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -37,9 +37,9 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.1.20",
+    "@uniweb/build": "0.1.22",
+    "@uniweb/core": "0.1.10",
     "@uniweb/kit": "0.1.5",
-    "@uniweb/runtime": "0.2.11",
-    "@uniweb/core": "0.1.8"
+    "@uniweb/runtime": "0.2.11"
   }
 }

package/partials/adding-pages.hbs

@@ -46,3 +46,32 @@ sections:
 This is clearer than prefix notation and easier to restructure.
 
 **Advanced:** Comma prefixes (`1,1-`, `1,2-`) also denote hierarchy, but explicit arrays are recommended for readability.
+
+### Page Ordering and Index Pages
+
+Parent controls which page is the "index" for its route. The index page gets the parent's route.
+
+**In `site.yml`** (for top-level pages):
+```yaml
+name: My Site
+pages: [home, about, features]  # First (home) is homepage at /
+# Or just name the homepage:
+index: home
+```
+
+**In `page.yml`** (for child pages):
+```yaml
+title: Documentation
+pages: [getting-started, installation, config]  # First is index for /docs
+# Or just name the index:
+index: getting-started
+```
+
+**How it works:**
+- `pages: [a, b, c]` — Explicit order, first item gets parent route
+- `index: name` — Just set the index, auto-discover the rest
+- Omit both — Sort by `order` prop, lowest becomes index
+
+**Example:** If `getting-started` is the index for `/docs`:
+- `pages/docs/getting-started/` → route `/docs`
+- `pages/docs/installation/` → route `/docs/installation`

package/partials/claude-md.hbs

@@ -138,6 +138,20 @@ sections:
 ```
 This is clearer than prefix notation (`1,1-`, `1,2-`) and easier to restructure.
 
+**Page ordering:** Parent controls which page is the index for its route:
+```yaml
+# In site.yml (top-level pages)
+pages: [home, about, docs]  # First is homepage at /
+index: home                  # Or just name the homepage
+
+# In page.yml (child pages)
+pages: [getting-started, installation]  # First is index for this route
+index: getting-started                   # Or just name the index
+```
+- `pages: [a, b, c]` — First gets parent route (becomes index)
+- `index: name` — Just set index, auto-discover rest
+- Omit both — Sort by `order` prop, lowest becomes index
+
 ## Component Development
 
 ### Props Interface