uniweb 0.6.18 → 0.6.20

package/README.md

@@ -85,6 +85,8 @@ my-project/
 
 **Pages are folders.** Create `pages/about/` with markdown files inside → visit `/about`. That's the whole routing model.
 
+**Batteries included:** File-based routing, pre-rendering, localization, dynamic routes, media processing, search indexing, and more. See [Building with Uniweb](https://github.com/uniweb/docs/blob/main/development/building-with-uniweb.md) for the full list.
+
 ### Content as Markdown
 
 ```markdown
@@ -163,7 +165,7 @@ After creating your project:
 
 3. **Learn the configuration** — Run `uniweb docs site` or `uniweb docs page` for quick reference on configuration options.
 
-4. **Create a section type** — Add a file to `foundation/src/sections/` (e.g., `Banner.jsx`) and rebuild. Bare files at the root are discovered automatically — no `meta.js` needed. Add `meta.js` when you want to declare params or presets. See the [Component Metadata Guide](./docs/component-metadata.md) for the full schema.
+4. **Create a section type** — Add a file to `foundation/src/sections/` (e.g., `Banner.jsx`) and rebuild. Bare files at the root are discovered automatically — no `meta.js` needed. Add `meta.js` when you want to declare params or presets. See the [Component Metadata Reference](https://github.com/uniweb/docs/blob/main/reference/component-metadata.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.
 
@@ -234,24 +236,27 @@ Start with local files deployed anywhere. The same foundation works across all t
 
 ---
 
-## Guides and Documentation
-
-[Developer Guides](./guides/developers/) — Building foundations and components, converting designs, component patterns, theming contexts
+## Documentation
 
-[Content Author Guides](./guides/authors/) — Writing pages in markdown, writing dynamic content, site setup, theming, recipes
+Full documentation is available at **[github.com/uniweb/docs](https://github.com/uniweb/docs)**:
 
-[Reference Docs](./docs/) — Full reference for all configuration, commands, and framework
+| Section | Topics |
+| ------- | ------ |
+| [Getting Started](https://github.com/uniweb/docs/tree/main/getting-started) | Introduction, quickstart, templates |
+| [Authoring](https://github.com/uniweb/docs/tree/main/authoring) | Writing content, site setup, theming, collections, translations |
+| [Development](https://github.com/uniweb/docs/tree/main/development) | Building foundations, component patterns, data fetching, layouts |
+| [Reference](https://github.com/uniweb/docs/tree/main/reference) | Configuration files, kit API, CLI commands, deployment |
 
 ### Quick Reference
 
 | Topic              | Guide                                                               |
 | ------------------ | ------------------------------------------------------------------- |
-| Content Structure  | [How markdown becomes component props](./docs/content-structure.md) |
-| Component Metadata | [The meta.js schema](./docs/component-metadata.md)                  |
-| Site Configuration | [site.yml reference](./docs/site-configuration.md)                  |
-| CLI Commands       | [create, build, docs, i18n](./docs/cli-commands.md)                 |
-| Templates          | [Built-in, official, and external templates](./docs/templates.md)   |
-| Deployment         | [Vercel, Netlify, Cloudflare, and more](./docs/deployment.md)       |
+| Content Structure  | [How markdown becomes component props](https://github.com/uniweb/docs/blob/main/reference/content-structure.md) |
+| Component Metadata | [The meta.js schema](https://github.com/uniweb/docs/blob/main/reference/component-metadata.md) |
+| Site Configuration | [site.yml reference](https://github.com/uniweb/docs/blob/main/reference/site-configuration.md) |
+| CLI Commands       | [create, build, docs, i18n](https://github.com/uniweb/docs/blob/main/reference/cli-commands.md) |
+| Templates          | [Built-in, official, and external templates](https://github.com/uniweb/docs/blob/main/getting-started/templates.md) |
+| Deployment         | [Vercel, Netlify, Cloudflare, and more](https://github.com/uniweb/docs/blob/main/reference/deployment.md) |
 
 ---
 
@@ -349,6 +354,10 @@ Yes. Content is pre-embedded in the initial HTML—no fetch waterfalls, no layou
 
 Pages can define data sources that auto-generate subroutes. A `/blog` page can have an index and a `[slug]` template that renders each post.
 
+**Is Uniweb good for documentation sites?**
+
+Yes — documentation is a natural fit. Content stays in markdown (easy to version, review, and contribute to), while the foundation handles navigation, search, and rendering. [Uniweb's own docs](https://github.com/uniweb/docs) use this pattern: pure markdown in a public repo, rendered by a separate foundation.
+
 ## Related Packages
 
 - [`@uniweb/build`](https://github.com/uniweb/build) — Foundation build tooling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.6.18",
+  "version": "0.6.20",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,7 +42,7 @@
     "tar": "^7.0.0",
     "@uniweb/core": "0.4.7",
     "@uniweb/kit": "0.5.10",
-    "@uniweb/runtime": "0.5.21",
-    "@uniweb/build": "0.6.15"
+    "@uniweb/build": "0.6.17",
+    "@uniweb/runtime": "0.5.21"
   }
 }

package/partials/agents-md.hbs

@@ -159,6 +159,10 @@ site/pages/
 
 Decimals insert between: `2.5-testimonials.md` goes between `2-` and `3-`.
 
+**Ignored files/folders:**
+- `README.md` — repo documentation, not site content
+- `_*.md` or `_*/` — drafts and private content (e.g., `_drafts/`, `_old-hero.md`)
+
 **page.yml:**
 ```yaml
 title: About Us
@@ -369,3 +373,23 @@ Use with: `bg-primary`, `text-primary`, `bg-primary/10`
 **Component not appearing** — Verify `meta.js` exists and doesn't have `hidden: true`. Rebuild: `cd foundation && pnpm build`.
 
 **Styles not applying** — Verify `@source` in `styles.css` includes your component paths. Check custom colors match `@theme` definitions.
+
+## Further Documentation
+
+Full Uniweb documentation is available at **https://github.com/uniweb/docs** — raw markdown files you can fetch directly.
+
+| Section | Path | Topics |
+|---------|------|--------|
+| **Getting Started** | `getting-started/` | What is Uniweb, quickstart guide, templates overview |
+| **Authoring** | `authoring/` | Writing content, site setup, collections, theming, linking, search, recipes, translations |
+| **Development** | `development/` | Building foundations, component patterns, data fetching, custom layouts, i18n, converting existing designs |
+| **Reference** | `reference/` | site.yml, page.yml, content structure, meta.js, kit hooks/components, theming tokens, CLI commands, deployment |
+
+**Quick access pattern:** `https://raw.githubusercontent.com/uniweb/docs/main/{section}/{page}.md`
+
+Examples:
+- Content structure details: `reference/content-structure.md`
+- Component metadata (meta.js): `reference/component-metadata.md`
+- Kit hooks and components: `reference/kit-reference.md`
+- Theming tokens: `reference/site-theming.md`
+- Data fetching patterns: `reference/data-fetching.md`

package/src/commands/i18n.js

@@ -4,11 +4,12 @@
  * Commands for managing site content internationalization.
  *
  * Usage:
- *   uniweb i18n extract           Extract translatable strings to manifest
- *   uniweb i18n init [locales]    Generate starter locale files from manifest
- *   uniweb i18n sync              Sync manifest with content changes
- *   uniweb i18n status            Show translation coverage per locale
- *   uniweb i18n --target <path>   Specify site directory explicitly
+ *   uniweb i18n extract             Extract/update translatable strings (default)
+ *   uniweb i18n generate [locales]  Generate starter locale files from manifest
+ *   uniweb i18n status              Show translation coverage per locale
+ *   uniweb i18n --target <path>     Specify site directory explicitly
+ *
+ * Aliases: sync → extract, init → generate
  *
  * When run from workspace root, auto-detects sites. If multiple exist,
  * prompts for selection.
@@ -81,9 +82,9 @@ export async function i18n(args) {
   // Parse --target option
   const { target, remainingArgs } = parseTargetOption(args)
 
-  // Default to 'sync' if no subcommand (or if first arg is an option)
+  // Default to 'extract' if no subcommand (or if first arg is an option)
   const firstArg = remainingArgs[0]
-  const effectiveSubcommand = !firstArg || firstArg.startsWith('-') ? 'sync' : firstArg
+  const effectiveSubcommand = !firstArg || firstArg.startsWith('-') ? 'extract' : firstArg
   const effectiveArgs = !firstArg || firstArg.startsWith('-') ? remainingArgs : remainingArgs.slice(1)
 
   // Find site root
@@ -98,14 +99,13 @@ export async function i18n(args) {
 
   switch (effectiveSubcommand) {
     case 'extract':
+    case 'sync':
       await runExtract(siteRoot, config, effectiveArgs)
       break
+    case 'generate':
     case 'init':
       await runInit(siteRoot, config, effectiveArgs)
       break
-    case 'sync':
-      await runSync(siteRoot, config, effectiveArgs)
-      break
     case 'status':
       await runStatus(siteRoot, config, effectiveArgs)
       break
@@ -228,13 +228,14 @@ async function loadSiteConfig(siteRoot) {
  */
 async function runExtract(siteRoot, config, args) {
   const verbose = args.includes('--verbose') || args.includes('-v')
+  const dryRun = args.includes('--dry-run')
   const collectionsOnly = args.includes('--collections-only') || args.includes('--collections')
   const noCollections = args.includes('--no-collections')
   // --with-collections is now a no-op (collections are included by default)
 
   // Extract page content (unless --collections-only)
   if (!collectionsOnly) {
-    log(`\n${colors.cyan}Extracting translatable content...${colors.reset}\n`)
+    log(`\n${colors.cyan}Extracting translatable content${dryRun ? ' (dry run)' : ''}...${colors.reset}\n`)
 
     // Check if site has been built
     const siteContentPath = join(siteRoot, 'dist', 'site-content.json')
@@ -247,22 +248,32 @@ async function runExtract(siteRoot, config, args) {
       // Dynamic import to avoid loading at CLI startup
       const { extractManifest, formatSyncReport } = await import('@uniweb/build/i18n')
 
+      // Check if this is a first-time extract (no previous manifest)
+      const manifestPath = join(siteRoot, config.localesDir, 'manifest.json')
+      const isUpdate = existsSync(manifestPath)
+
       const { manifest, report } = await extractManifest(siteRoot, {
         localesDir: config.localesDir,
         siteContentPath,
         verbose,
+        dryRun,
       })
 
       // Show results
       const unitCount = Object.keys(manifest.units).length
       success(`Extracted ${unitCount} translatable strings`)
 
-      if (report) {
+      // Show sync report for updates (skip on first extract — everything would be "added")
+      if (report && isUpdate) {
         log('')
         log(formatSyncReport(report))
       }
 
-      log(`\nManifest written to: ${colors.dim}${config.localesDir}/manifest.json${colors.reset}`)
+      if (dryRun) {
+        log(`\n${colors.dim}Dry run — no files were modified.${colors.reset}`)
+      } else {
+        log(`\nManifest written to: ${colors.dim}${config.localesDir}/manifest.json${colors.reset}`)
+      }
 
       if (config.locales.length === 0) {
         log(`\n${colors.dim}No translation files found in ${config.localesDir}/.`)
@@ -277,7 +288,7 @@ async function runExtract(siteRoot, config, args) {
 
   // Extract collection content (by default, skip with --no-collections)
   if (!noCollections) {
-    log(`\n${colors.cyan}Extracting collection content...${colors.reset}\n`)
+    log(`\n${colors.cyan}Extracting collection content${dryRun ? ' (dry run)' : ''}...${colors.reset}\n`)
 
     // Check if collections exist
     const dataDir = join(siteRoot, 'public', 'data')
@@ -293,20 +304,28 @@ async function runExtract(siteRoot, config, args) {
     try {
       const { extractCollectionManifest, formatSyncReport } = await import('@uniweb/build/i18n')
 
+      const collectionsManifestPath = join(siteRoot, config.localesDir, 'collections', 'manifest.json')
+      const isUpdate = existsSync(collectionsManifestPath)
+
       const { manifest, report } = await extractCollectionManifest(siteRoot, {
         localesDir: config.localesDir,
+        dryRun,
       })
 
       const unitCount = Object.keys(manifest.units).length
       if (unitCount > 0) {
         success(`Extracted ${unitCount} translatable strings from collections`)
 
-        if (report) {
+        if (report && isUpdate) {
           log('')
           log(formatSyncReport(report))
         }
 
-        log(`\nManifest written to: ${colors.dim}${config.localesDir}/collections/manifest.json${colors.reset}`)
+        if (dryRun) {
+          log(`\n${colors.dim}Dry run — no files were modified.${colors.reset}`)
+        } else {
+          log(`\nManifest written to: ${colors.dim}${config.localesDir}/collections/manifest.json${colors.reset}`)
+        }
       } else {
         log(`${colors.dim}No translatable content found in collections.${colors.reset}`)
       }
@@ -319,13 +338,13 @@ async function runExtract(siteRoot, config, args) {
 }
 
 /**
- * Init command - generate starter translation files from manifest
+ * Generate command - generate starter translation files from manifest
  *
  * Usage:
- *   uniweb i18n init es fr         Initialize specific locales
- *   uniweb i18n init               Initialize all configured locales
- *   uniweb i18n init --empty       Use empty strings instead of source text
- *   uniweb i18n init --force       Overwrite existing files entirely
+ *   uniweb i18n generate es fr     Generate specific locales
+ *   uniweb i18n generate           Generate all configured locales
+ *   uniweb i18n generate --empty   Use empty strings instead of source text
+ *   uniweb i18n generate --force   Overwrite existing files entirely
  */
 async function runInit(siteRoot, config, args) {
   const useEmpty = args.includes('--empty')
@@ -360,7 +379,7 @@ async function runInit(siteRoot, config, args) {
 
   if (!targetLocales || targetLocales.length === 0) {
     error('No target locales specified.')
-    log(`${colors.dim}Specify locales as arguments (e.g., "uniweb i18n init es fr")`)
+    log(`${colors.dim}Specify locales as arguments (e.g., "uniweb i18n generate es fr")`)
     log(`or configure them in site.yml under i18n.locales.${colors.reset}`)
     process.exit(1)
   }
@@ -425,55 +444,6 @@ async function runInit(siteRoot, config, args) {
   log(`  3. Run 'uniweb i18n status' to check coverage${colors.reset}`)
 }
 
-/**
- * Sync command - detect changes and update manifest
- */
-async function runSync(siteRoot, config, args) {
-  const verbose = args.includes('--verbose') || args.includes('-v')
-  const dryRun = args.includes('--dry-run')
-
-  log(`\n${colors.cyan}Syncing i18n manifest...${colors.reset}\n`)
-
-  // Check if site has been built
-  const siteContentPath = join(siteRoot, 'dist', 'site-content.json')
-  if (!existsSync(siteContentPath)) {
-    error('Site content not found. Run "uniweb build" first.')
-    process.exit(1)
-  }
-
-  // Check if manifest exists
-  const manifestPath = join(siteRoot, config.localesDir, 'manifest.json')
-  if (!existsSync(manifestPath)) {
-    warn('No existing manifest found. Running extract instead.')
-    return runExtract(siteRoot, config, args)
-  }
-
-  try {
-    const { extractManifest, formatSyncReport } = await import('@uniweb/build/i18n')
-
-    if (dryRun) {
-      log(`${colors.dim}(dry run - no files will be modified)${colors.reset}\n`)
-    }
-
-    const { manifest, report } = await extractManifest(siteRoot, {
-      localesDir: config.localesDir,
-      siteContentPath,
-      verbose,
-      dryRun,
-    })
-
-    log(formatSyncReport(report))
-
-    if (!dryRun) {
-      success('\nManifest updated')
-    }
-  } catch (err) {
-    error(`Sync failed: ${err.message}`)
-    if (verbose) console.error(err)
-    process.exit(1)
-  }
-}
-
 /**
  * Status command - show translation coverage
  */
@@ -1458,10 +1428,8 @@ ${colors.bright}Usage:${colors.reset}
 
 ${colors.bright}Commands:${colors.reset}
   ${colors.dim}# Hash-based (granular) translation${colors.reset}
-  (default)    Same as sync - extract/update strings (runs if no command given)
-  extract      Extract translatable strings to locales/manifest.json
-  init         Generate starter locale files from manifest keys
-  sync         Update manifest with content changes (detects moved/changed content)
+  extract      Extract/update translatable strings (default if no command given)
+  generate     Generate starter locale files from manifest keys
   status       Show translation coverage per locale
   audit        Find stale translations (no longer in manifest) and missing ones
 
@@ -1475,9 +1443,9 @@ ${colors.bright}Commands:${colors.reset}
 ${colors.bright}Options:${colors.reset}
   -t, --target <path>  Site directory (auto-detected if not specified)
   --verbose            Show detailed output
-  --dry-run            (sync/prune) Show changes without writing files
-  --empty              (init) Use empty strings instead of source text
-  --force              (init) Overwrite existing locale files entirely
+  --dry-run            (extract/prune) Preview changes without writing files
+  --empty              (generate) Use empty strings instead of source text
+  --force              (generate) Overwrite existing locale files entirely
   --clean              (audit) Remove stale entries from locale files
   --missing            (status) List all missing strings instead of summary
   --freeform           (status/prune) Include free-form translation status
@@ -1500,7 +1468,7 @@ ${colors.bright}Configuration:${colors.reset}
 ${colors.bright}Workflow:${colors.reset}
   1. Build your site:           uniweb build
   2. Extract strings:           uniweb i18n extract
-  3. Initialize locale files:   uniweb i18n init es fr
+  3. Generate locale files:     uniweb i18n generate es fr
   4. Translate locale files:    Edit locales/es.json, locales/fr.json, etc.
   5. Build with translations:   uniweb build (generates locale-specific output)
 
@@ -1519,18 +1487,18 @@ ${colors.bright}File Structure:${colors.reset}
 
 ${colors.bright}Examples:${colors.reset}
   ${colors.dim}# Hash-based workflow${colors.reset}
-  uniweb i18n extract              # Extract all translatable strings
-  uniweb i18n extract --verbose    # Show extracted strings
+  uniweb i18n extract                     # Extract all translatable strings
+  uniweb i18n extract --dry-run           # Preview without writing
+  uniweb i18n extract --verbose           # Show extracted strings
   uniweb i18n extract --no-collections    # Pages only (skip collections)
-  uniweb i18n init es fr           # Create starter files for Spanish and French
-  uniweb i18n init --empty         # Create files with empty values (for translators)
-  uniweb i18n init --force         # Overwrite existing locale files
-  uniweb i18n sync                 # Update manifest after content changes
-  uniweb i18n status               # Show coverage for all locales
-  uniweb i18n status es            # Show coverage for Spanish only
+  uniweb i18n generate es fr              # Create starter files for Spanish and French
+  uniweb i18n generate --empty            # Create files with empty values (for translators)
+  uniweb i18n generate --force            # Overwrite existing locale files
+  uniweb i18n status                      # Show coverage for all locales
+  uniweb i18n status es                   # Show coverage for Spanish only
   uniweb i18n status es --missing --json  # Export missing for AI translation
-  uniweb i18n audit                # Find stale and missing translations
-  uniweb i18n audit --clean        # Remove stale entries
+  uniweb i18n audit                       # Find stale and missing translations
+  uniweb i18n audit --clean               # Remove stale entries
 
   ${colors.dim}# Free-form workflow (complete section replacement)${colors.reset}
   uniweb i18n init-freeform es pages/about hero
@@ -1542,6 +1510,10 @@ ${colors.bright}Examples:${colors.reset}
   uniweb i18n prune --freeform --dry-run  # Preview orphan cleanup
   uniweb i18n --target site        # Specify site directory explicitly
 
+${colors.bright}Aliases:${colors.reset}
+  sync → extract   (backward-compatible)
+  init → generate  (backward-compatible)
+
 ${colors.bright}Notes:${colors.reset}
   Run from a site directory to operate on that site.
   Run from workspace root to auto-detect sites (prompts if multiple).