uniweb 1.0.0 → 1.0.2

package/partials/adding-pages.hbs

@@ -0,0 +1,77 @@
+### Adding a New Page
+
+1. Create a folder: `site/pages/my-page/`
+2. Add `page.yml`:
+   ```yaml
+   title: My Page
+   ```
+3. Add section files: `1-hero.md`, `2-content.md`, etc.
+
+### Section Ordering
+
+By default, sections are discovered from `.md` files and sorted by numeric prefix (`1-`, `2-`, `3-`).
+
+**Decimal prefixes** allow inserting sections without renumbering: `2.5-` sorts between `2-` and `3-`.
+
+For explicit control, use the `sections` property in `page.yml`:
+
+```yaml
+title: My Page
+sections:
+  - hero
+  - features
+  - pricing
+```
+
+This makes reordering easy (move lines) and allows commenting out sections temporarily.
+
+**Options:**
+- `sections: *` or omit — auto-discover and sort `.md` files by prefix (default)
+- `sections: [hero, features]` — explicit ordering, no prefixes needed
+- `sections: []` — pure route with no content sections
+
+### Section Hierarchy (Subsections)
+
+For parent-child relationships, use the explicit array with nesting:
+
+```yaml
+sections:
+  - hero
+  - features:
+      - logocloud
+      - stats
+  - pricing
+```
+
+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`