uniweb 0.3.3 → 0.3.4

package/README.md

@@ -106,7 +106,16 @@ role: Lead Architect
 ```
 ````
 
-Components receive validated, localized data. Natural content stays in markdown; structured data goes in tagged blocks (YAML or JSON).
+Access the parsed data via `content.data`:
+
+```jsx
+function TeamCard({ content }) {
+  const member = content.data['team-member']
+  return <div>{member.name} — {member.role}</div>
+}
+```
+
+Natural content stays in markdown; structured data goes in tagged blocks (YAML or JSON).
 
 ### Components as React
 
@@ -648,6 +657,76 @@ 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.
 
+## Common Gotchas
+
+### Homepage Configuration
+
+Set your homepage with `index:` in `site.yml`:
+
+```yaml
+# site.yml
+index: home  # The page folder that becomes /
+```
+
+The `index:` option tells the build which page folder becomes the root route (`/`). The page still exists in `pages/home/`, but visitors access it at `/`.
+
+Don't confuse this with `pages:` (which explicitly lists pages and hides any not listed).
+
+### Content Shapes
+
+Lists and items in markdown become **objects**, not strings. A bullet list:
+
+```markdown
+- First item
+- Second item
+```
+
+Becomes:
+
+```js
+content.items = [
+  { title: "First item", paragraphs: [], links: [], imgs: [] },
+  { title: "Second item", paragraphs: [], links: [], imgs: [] }
+]
+```
+
+Each item has the same structure as a content block. See [Content Structure](./docs/content-structure.md) for the full shape.
+
+### Tagged Data Blocks
+
+Tagged code blocks like:
+
+````markdown
+```yaml:team-member
+name: Sarah Chen
+role: Lead Architect
+```
+````
+
+Are accessible via `content.data`:
+
+```jsx
+function TeamMember({ content }) {
+  const member = content.data['team-member']
+  return <div>{member.name} - {member.role}</div>
+}
+```
+
+The tag name (after the colon) becomes the key in `content.data`.
+
+### Root vs Package Commands
+
+In a Uniweb workspace, commands run differently at different levels:
+
+| Location | Command | What it does |
+|----------|---------|--------------|
+| Project root | `pnpm build` | Builds all packages (foundation + site) |
+| Project root | `pnpm dev` | Starts dev server for site |
+| `foundation/` | `uniweb build` | Builds just the foundation |
+| `site/` | `uniweb build` | Builds just the site |
+
+For day-to-day development, run `pnpm dev` from the project root. The workspace scripts handle the rest.
+
 ## Related Packages
 
 - [`@uniweb/build`](https://github.com/uniweb/build) — Foundation build tooling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "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.2.1",
-    "@uniweb/core": "0.2.1",
-    "@uniweb/kit": "0.2.1",
-    "@uniweb/runtime": "0.3.0"
+    "@uniweb/build": "0.2.2",
+    "@uniweb/core": "0.2.2",
+    "@uniweb/runtime": "0.3.0",
+    "@uniweb/kit": "0.2.1"
   }
 }

package/templates/multi/sites/main/site.yml.hbs

@@ -2,6 +2,9 @@ name: {{projectName}}
 description: Main site for {{projectName}}
 foundation: default
 
+# Homepage - specifies which page folder becomes the root route (/)
+index: home
+
 theme:
   primary: '#3b82f6'
 

package/templates/single/site/site.yml.hbs

@@ -1,5 +1,8 @@
 name: {{projectName}}
 
+# Homepage - specifies which page folder becomes the root route (/)
+index: home
+
 theme:
   primary: '#3b82f6'