uniweb 0.2.43 → 0.2.44

package/README.md

@@ -125,6 +125,52 @@ export function Hero({ content, params }) {
 
 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.
 
+## Next Steps
+
+After creating your project:
+
+1. **Explore the structure** — Browse `site/pages/` to see how content is organized. Each page folder contains `page.yml` (metadata) and `.md` files (sections).
+
+2. **Generate component docs** — Run `pnpm uniweb docs` to create `COMPONENTS.md` with all available components, their parameters, and presets.
+
+3. **Learn the configuration** — Run `uniweb docs site` or `uniweb docs page` for quick reference on configuration options.
+
+4. **Create a component** — Add a folder in `foundation/src/components/`, create `index.jsx` and `meta.js`, then rebuild. See the [meta.js guide](https://github.com/uniweb/cli/blob/main/docs/meta/README.md) for the full schema.
+
+The `meta.js` file defines what content and parameters a component accepts. The runtime uses this metadata to apply defaults and guarantee content structure—no defensive null checks needed in your component code.
+
+### Your First Content Change
+
+Open `site/pages/home/1-hero.md` and edit the headline:
+
+```markdown
+---
+type: Hero
+---
+
+# Your New Headline Here
+
+Updated description text.
+
+[Get Started](/about)
+```
+
+Save and see the change instantly in your browser.
+
+### Your First Component Change
+
+Open `foundation/src/components/Hero/index.jsx`. The component receives parsed content:
+
+```jsx
+export function Hero({ content, params }) {
+  const { title } = content.main.header      // "Your New Headline Here"
+  const { paragraphs } = content.main.body   // ["Updated description text."]
+  // Edit the JSX below...
+}
+```
+
+Change the JSX, save, and the dev server hot-reloads your changes.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.2.43",
+  "version": "0.2.44",
   "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.24",
-    "@uniweb/kit": "0.1.6",
+    "@uniweb/build": "0.1.25",
     "@uniweb/runtime": "0.2.12",
-    "@uniweb/core": "0.1.11"
+    "@uniweb/core": "0.1.11",
+    "@uniweb/kit": "0.1.7"
   }
 }

package/partials/config-reference.hbs

@@ -0,0 +1,67 @@
+## Configuration Reference
+
+### site.yml
+
+Site-wide configuration in `site/site.yml`:
+
+```yaml
+name: My Site                    # Site name
+defaultLanguage: en              # Default locale code
+foundation: foundation           # Foundation package name
+
+# Page ordering (controls top-level navigation)
+pages: [home, about, features]   # First is homepage at /
+# Or just name the homepage:
+index: home
+
+# Internationalization
+i18n:
+  locales: [es, fr]              # Non-default locales to build
+  localesDir: locales            # Translation files directory
+
+# Build options
+build:
+  prerender: true                # Enable static site generation
+```
+
+### page.yml
+
+Page-level configuration in `site/pages/[page]/page.yml`:
+
+```yaml
+title: About Us                  # Page title (used in <title> and nav)
+description: Learn about us      # Meta description
+label: About                     # Short nav label (optional)
+order: 2                         # Navigation sort order
+
+# Child page ordering
+pages: [intro, guide, reference] # First is index for this route
+index: intro                     # Or just name the index
+
+# Navigation visibility
+hidden: true                     # Hide from all navigation
+hideInHeader: true               # Hide from header only
+hideInFooter: true               # Hide from footer only
+
+# Layout overrides
+layout:
+  header: false                  # Don't render header
+  footer: false                  # Don't render footer
+
+# Section ordering
+sections:                        # Explicit section order
+  - hero
+  - features:                    # Nested = subsections
+      - logocloud
+      - stats
+  - pricing
+
+# SEO
+seo:
+  noindex: true
+  image: /og-image.png
+  changefreq: monthly
+  priority: 0.8
+```
+
+Run `pnpm uniweb docs site` or `pnpm uniweb docs page` for complete reference.

package/src/commands/docs.js

@@ -1,10 +1,14 @@
 /**
  * Docs Command
  *
- * Generates markdown documentation from foundation schema.
+ * Generates markdown documentation from foundation schema and
+ * provides configuration references.
  *
  * Usage:
- *   uniweb docs                    # Generate docs for current directory
+ *   uniweb docs                    # Generate COMPONENTS.md
+ *   uniweb docs site               # Show site.yml reference
+ *   uniweb docs page               # Show page.yml reference
+ *   uniweb docs meta               # Show component meta.js reference
  *   uniweb docs --output README.md # Custom output filename
  *   uniweb docs --from-source      # Build schema from source (no build required)
  *   uniweb docs --target <path>    # Specify foundation directory explicitly
@@ -53,6 +57,195 @@ function info(message) {
   console.log(`${colors.cyan}→${colors.reset} ${message}`)
 }
 
+// =============================================================================
+// Reference Content
+// =============================================================================
+
+const SITE_REFERENCE = `
+${colors.cyan}${colors.bright}site.yml Reference${colors.reset}
+
+Site-wide configuration for your Uniweb project.
+
+${colors.bright}Core Settings:${colors.reset}
+  ${colors.cyan}name${colors.reset}              Site name (used in metadata and browser tab)
+  ${colors.cyan}defaultLanguage${colors.reset}   Default locale code (default: "en")
+  ${colors.cyan}foundation${colors.reset}        Foundation package name ("foundation" for local)
+
+${colors.bright}Page Ordering:${colors.reset}
+  ${colors.cyan}pages${colors.reset}             Array of page folder names
+                    First item becomes homepage at /
+                    Example: [home, about, docs, pricing]
+  ${colors.cyan}index${colors.reset}             Alternative: just name the homepage
+                    Rest are auto-discovered
+
+${colors.bright}Internationalization:${colors.reset}
+  ${colors.cyan}i18n.locales${colors.reset}      Locales to build (array or "*" for all)
+                    Example: [es, fr, de]
+  ${colors.cyan}i18n.localesDir${colors.reset}   Translation files directory (default: "locales")
+
+${colors.bright}Build Options:${colors.reset}
+  ${colors.cyan}build.prerender${colors.reset}   Enable static HTML generation (default: false)
+                    Generates SEO-friendly static pages
+
+${colors.bright}Example:${colors.reset}
+  ${colors.dim}name: My Site
+  defaultLanguage: en
+  foundation: foundation
+  pages: [home, about, docs]
+  i18n:
+    locales: [es, fr]
+  build:
+    prerender: true${colors.reset}
+
+${colors.dim}Schema: https://raw.githubusercontent.com/uniweb/cli/main/schemas/site.schema.json${colors.reset}
+`
+
+const PAGE_REFERENCE = `
+${colors.cyan}${colors.bright}page.yml Reference${colors.reset}
+
+Page-level configuration in site/pages/[page]/page.yml
+
+${colors.bright}Basic Metadata:${colors.reset}
+  ${colors.cyan}title${colors.reset}             Page title (browser tab, nav, SEO)
+  ${colors.cyan}description${colors.reset}       Meta description for SEO
+  ${colors.cyan}label${colors.reset}             Short nav label (defaults to title)
+  ${colors.cyan}order${colors.reset}             Navigation sort order (lower = first)
+
+${colors.bright}Child Page Ordering:${colors.reset}
+  ${colors.cyan}pages${colors.reset}             Array of child page names
+                    First becomes index for this route
+  ${colors.cyan}index${colors.reset}             Alternative: just name the index page
+
+${colors.bright}Navigation Visibility:${colors.reset}
+  ${colors.cyan}hidden${colors.reset}            Hide from all navigation (page still exists)
+  ${colors.cyan}hideInHeader${colors.reset}      Hide from header nav only
+  ${colors.cyan}hideInFooter${colors.reset}      Hide from footer nav only
+
+${colors.bright}Layout Overrides:${colors.reset}
+  ${colors.cyan}layout.header${colors.reset}     Show header on this page (default: true)
+  ${colors.cyan}layout.footer${colors.reset}     Show footer on this page (default: true)
+  ${colors.cyan}layout.leftPanel${colors.reset}  Show left sidebar (default: true)
+  ${colors.cyan}layout.rightPanel${colors.reset} Show right sidebar (default: true)
+
+${colors.bright}Section Control:${colors.reset}
+  ${colors.cyan}sections${colors.reset}          "*" for auto-discover, or explicit array
+                    Nested arrays create subsections:
+                    - hero
+                    - features:
+                        - logocloud
+                        - stats
+
+${colors.bright}SEO Options:${colors.reset}
+  ${colors.cyan}seo.noindex${colors.reset}       Prevent search engine indexing
+  ${colors.cyan}seo.image${colors.reset}         Open Graph image URL
+  ${colors.cyan}seo.changefreq${colors.reset}    Sitemap hint (daily, weekly, monthly...)
+  ${colors.cyan}seo.priority${colors.reset}      Sitemap priority (0.0 to 1.0)
+
+${colors.bright}Example:${colors.reset}
+  ${colors.dim}title: About Us
+  description: Learn about our company
+  order: 2
+  hideInFooter: true
+  layout:
+    rightPanel: false
+  seo:
+    image: /about-og.png${colors.reset}
+
+${colors.dim}Schema: https://raw.githubusercontent.com/uniweb/cli/main/schemas/page.schema.json${colors.reset}
+`
+
+const META_REFERENCE = `
+${colors.cyan}${colors.bright}Component meta.js Reference${colors.reset}
+
+Component metadata in foundation/src/components/[Name]/meta.js
+
+${colors.bright}Identity:${colors.reset}
+  ${colors.cyan}title${colors.reset}             Display name in editor
+  ${colors.cyan}description${colors.reset}       What the component does
+  ${colors.cyan}category${colors.reset}          Grouping: "impact", "showcase", "structure"
+  ${colors.cyan}purpose${colors.reset}           Single verb: Introduce, Express, Explain
+  ${colors.cyan}hidden${colors.reset}            If true, not selectable in frontmatter
+
+${colors.bright}Content Expectations:${colors.reset}
+  ${colors.cyan}content${colors.reset}           Object describing expected markdown structure
+                    Keys: title, pretitle, subtitle, paragraphs, links, items
+                    Values: "Description [count]"
+                    Count: [1], [1-3], [2+]
+
+${colors.bright}Parameters:${colors.reset}
+  ${colors.cyan}params${colors.reset}            Object of configurable parameters
+                    Each param has: type, label, options, default
+                    Types: "select", "boolean", "string", "number"
+
+${colors.bright}Presets:${colors.reset}
+  ${colors.cyan}presets${colors.reset}           Named parameter combinations
+                    Each preset: { label, params: {...} }
+
+${colors.bright}Special:${colors.reset}
+  ${colors.cyan}background${colors.reset}        true if component supports background images
+  ${colors.cyan}data${colors.reset}              Dynamic data binding ("articles", "events:5")
+
+${colors.bright}Example:${colors.reset}
+  ${colors.dim}export default {
+    title: 'Hero Banner',
+    description: 'Bold hero section with headline and CTA',
+    category: 'impact',
+    background: true,
+
+    content: {
+      pretitle: 'Eyebrow text',
+      title: 'Headline',
+      paragraphs: 'Description [1-2]',
+      links: 'CTA buttons [1-2]',
+    },
+
+    params: {
+      theme: {
+        type: 'select',
+        options: ['gradient', 'glass', 'dark'],
+        default: 'gradient',
+      },
+      layout: {
+        type: 'select',
+        options: ['center', 'left', 'split'],
+        default: 'center',
+      },
+    },
+
+    presets: {
+      default: { label: 'Centered', params: { theme: 'gradient', layout: 'center' } },
+      minimal: { label: 'Minimal', params: { theme: 'light', layout: 'left' } },
+    },
+  }${colors.reset}
+
+${colors.bright}Runtime Benefits:${colors.reset}
+  - Content structure is guaranteed (no null checks needed)
+  - Param defaults are applied automatically
+  - Components receive clean { content, params } props
+
+${colors.dim}Full guide: https://github.com/uniweb/cli/blob/main/docs/meta/README.md${colors.reset}
+`
+
+// =============================================================================
+// Subcommand Handlers
+// =============================================================================
+
+function showSiteReference() {
+  log(SITE_REFERENCE)
+}
+
+function showPageReference() {
+  log(PAGE_REFERENCE)
+}
+
+function showMetaReference() {
+  log(META_REFERENCE)
+}
+
+// =============================================================================
+// Original Docs Functionality
+// =============================================================================
+
 /**
  * Parse command line arguments
  */
@@ -85,25 +278,32 @@ function parseArgs(args) {
  */
 function showHelp() {
   log(`
-${colors.bright}uniweb docs${colors.reset} - Generate component documentation
+${colors.bright}uniweb docs${colors.reset} - Documentation and configuration references
 
 ${colors.dim}Usage:${colors.reset}
   uniweb docs                         Generate COMPONENTS.md
-  uniweb docs --output DOCS.md        Custom output filename
-  uniweb docs --from-source           Build schema from source (no build required)
-  uniweb docs --target foundation     Specify foundation directory explicitly
+  uniweb docs site                    Show site.yml configuration reference
+  uniweb docs page                    Show page.yml configuration reference
+  uniweb docs meta                    Show component meta.js reference
 
-${colors.dim}Options:${colors.reset}
+${colors.dim}Generation Options:${colors.reset}
   -o, --output <file>    Output filename (default: COMPONENTS.md)
   -s, --from-source      Read meta.js files directly instead of schema.json
   -t, --target <path>    Foundation directory (auto-detected if not specified)
   -h, --help             Show this help message
 
+${colors.dim}Examples:${colors.reset}
+  uniweb docs                         Generate component docs
+  uniweb docs site                    Quick reference for site.yml options
+  uniweb docs page                    Quick reference for page.yml options
+  uniweb docs meta                    Learn about component meta.js schema
+  uniweb docs --output DOCS.md        Custom output filename
+  uniweb docs --from-source           Generate without building first
+
 ${colors.dim}Notes:${colors.reset}
   Run from a foundation directory to generate docs there.
-  Run from a site directory to auto-detect the linked foundation
-  and generate docs in the site folder for convenience.
-  Run from workspace root to auto-detect foundations (prompts if multiple).
+  Run from a site directory to auto-detect the linked foundation.
+  Run from workspace root to auto-detect foundations.
 `)
 }
 
@@ -158,16 +358,11 @@ async function resolveFoundationFromSite(siteDir) {
 }
 
 /**
- * Main docs command
+ * Generate component documentation (original functionality)
  */
-export async function docs(args) {
+async function generateComponentDocs(args) {
   const options = parseArgs(args)
 
-  if (options.help) {
-    showHelp()
-    return
-  }
-
   const projectDir = resolve(process.cwd())
   let foundationDir = projectDir
   let outputDir = projectDir
@@ -254,3 +449,40 @@ export async function docs(args) {
     process.exit(1)
   }
 }
+
+// =============================================================================
+// Main Command Entry Point
+// =============================================================================
+
+/**
+ * Main docs command - handles subcommands and generates documentation
+ */
+export async function docs(args) {
+  // Check for subcommand as first argument
+  const firstArg = args[0]
+
+  // Handle reference subcommands
+  if (firstArg === 'site') {
+    showSiteReference()
+    return
+  }
+
+  if (firstArg === 'page') {
+    showPageReference()
+    return
+  }
+
+  if (firstArg === 'meta') {
+    showMetaReference()
+    return
+  }
+
+  // Handle help
+  if (firstArg === '--help' || firstArg === '-h') {
+    showHelp()
+    return
+  }
+
+  // Default: generate component documentation
+  await generateComponentDocs(args)
+}

package/src/index.js

@@ -341,6 +341,12 @@ ${colors.bright}Build Options:${colors.reset}
 
   Pre-rendering is enabled by default when build.prerender: true in site.yml
 
+${colors.bright}Docs Subcommands:${colors.reset}
+  docs               Generate COMPONENTS.md from foundation schema
+  docs site          Show site.yml configuration reference
+  docs page          Show page.yml configuration reference
+  docs meta          Show component meta.js reference
+
 ${colors.bright}Docs Options:${colors.reset}
   --output <file>    Output filename (default: COMPONENTS.md)
   --from-source      Read meta.js files directly instead of schema.json

package/templates/multi/template/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+  "yaml.schemas": {
+    "https://raw.githubusercontent.com/uniweb/cli/main/schemas/site.schema.json": "**/site.yml",
+    "https://raw.githubusercontent.com/uniweb/cli/main/schemas/page.schema.json": "**/page.yml"
+  }
+}

package/templates/single/template/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+  "yaml.schemas": {
+    "https://raw.githubusercontent.com/uniweb/cli/main/schemas/site.schema.json": "site/site.yml",
+    "https://raw.githubusercontent.com/uniweb/cli/main/schemas/page.schema.json": "**/page.yml"
+  }
+}