uniweb 0.8.26 → 0.8.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.26",
+  "version": "0.8.28",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "0.5.15",
-    "@uniweb/runtime": "0.6.21",
-    "@uniweb/kit": "0.7.16"
+    "@uniweb/core": "0.5.17",
+    "@uniweb/kit": "0.7.18",
+    "@uniweb/runtime": "0.6.23"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.8.25",
+    "@uniweb/build": "0.8.27",
     "@uniweb/content-reader": "1.1.4",
-    "@uniweb/semantic-parser": "1.1.7"
+    "@uniweb/semantic-parser": "1.1.8"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -138,6 +138,15 @@ The decision rule: **would a content author need to change this?** Yes → it be
 
 Start with the content, not the component. Write the markdown a content author would naturally write, check what content shape the parser produces, *then* build the component to receive it.
 
+**Markdown order ≠ rendering order.** The parser extracts content into a flat structure (`title`, `icons`, `images`, `paragraphs`). The component decides how to arrange these visually. Don't write markdown in visual order — write it in semantic order. Start sections with the heading, then add icons, images, and text in any order:
+
+```markdown
+# Site Name               ← title — always start with the heading
+![](lu-graduation-cap)    ← icon — component controls where this renders
+```
+
+Placing content *before* the first heading changes the parse: headings after body content become items, not the section title. This is by design — it's how repeating content groups (cards, features) are created.
+
 ### Section Format
 
 Each `.md` file is a section. Frontmatter on top, content below:
@@ -173,7 +182,7 @@ content = {
   pretitle: '',     // Heading before main title (auto-detected)
   subtitle: '',     // Heading after title (string or string[] for multi-line)
   paragraphs: [],   // Text blocks
-  links: [],        // { href, label, role } — standalone links become buttons
+  links: [],        // { href, label, role } — standalone links (not inside lists)
   images: [],       // { src, alt, role, href }
   icons: [],        // { library, name, role }
   videos: [],       // { src, alt, role, poster, href }
@@ -249,6 +258,20 @@ Enterprise-grade security.     │  content.items[1].paragraphs[0] = "Enterprise
 
 Headings before the main title become `pretitle`. Headings after the main title at a lower importance become `subtitle`. Headings that appear after body content (paragraphs, links, images) start the `items` array.
 
+**Subtitle vs items:** A heading immediately after the title becomes `subtitle` only when it is **exactly one level deeper** (H1→H2, H2→H3). Skipping levels (H1→H3) breaks the group — the deeper heading starts items instead. If you want items without a subtitle, use a `---` divider or a paragraph to close the title group:
+
+```markdown
+# Our Stats                       │  content.title = "Our Stats"
+---                                │  ← divider closes the title group
+## 15,000+                        │  content.items[0].title = "15,000+"
+Students from 90 countries        │  content.items[0].paragraphs[0]
+                                   │
+## 200+                           │  content.items[1].title = "200+"
+Programs offered                  │  content.items[1].paragraphs[0]
+```
+
+Without the `---`, `## 15,000+` would become `content.subtitle` instead of an item.
+
 ### Choosing how to model content
 
 You have three layers. Most of the design skill is choosing between them:
@@ -477,6 +500,8 @@ export default function Grid({ block, params }) {
 }
 ```
 
+**Data and child blocks:** Page-level `data:` is available to all blocks on the page, including children. Each child block resolves data independently through the same page → site hierarchy. If a child component needs data, declare it in the child's `meta.js` or in the child section's frontmatter (`data: articles`).
+
 ### Section Backgrounds
 
 Set `background` in frontmatter — the runtime renders it automatically:
@@ -529,6 +554,7 @@ id: about                   # Stable identity (for page: links, survives moves)
 order: 2                    # Navigation sort position
 pages: [team, history, ...] # Child page order (... = rest). Without ... = strict (hides unlisted)
 index: getting-started      # Which child page is the index
+redirect: academic          # Redirect to child page (relative or absolute path, or URL)
 ```
 
 **site.yml:**
@@ -720,6 +746,8 @@ export const vars = {
 
 Sites override in `theme.yml` under `vars:`. Components use: `py-[var(--section-padding-y)]`, `h-[var(--header-height)]`.
 
+Tailwind v4 also supports a shorthand: `py-(--section-padding-y)`. This requires registering the variable in `styles.css` via `@theme inline { --section-padding-y: <default>; }`. Use the shorthand for vars referenced across many components; otherwise the bracket syntax works without registration.
+
 ### Design richness beyond tokens
 
 Tokens handle context adaptation — the hard problem. **They are a floor, not a ceiling.** A great foundation adds design vocabulary on top:
@@ -764,6 +792,7 @@ All non-reserved frontmatter fields become `params`. Reserved: `type`, `preset`,
 | `block.insets` | Block[] | Inline `@Component` references |
 | `block.getInset(refId)` | Block | Lookup inset by refId |
 | `block.properties` | object | Raw frontmatter |
+| `block.rawContent` | object | ProseMirror document — passed internally when using `<Article block={block} />` |
 | `block.themeName` | string | `"light"`, `"medium"`, `"dark"` |
 | `block.stableId` | string | Stable ID from filename or `id:` |
 
@@ -817,10 +846,10 @@ Kit provides `H1` through `H6` — use the appropriate level for semantic hierar
 **Full content rendering** (article/docs sections where the author controls the flow):
 
 ```jsx
-import { Section, Render } from '@uniweb/kit'
+import { Section, Article } from '@uniweb/kit'
 
 <Section block={block} width="lg" padding="md" />
-<Render content={block.parsedContent} block={block} />
+<Article block={block} />
 ```
 
 **Visuals:**
@@ -835,7 +864,7 @@ import { Visual } from '@uniweb/kit'
 
 **Rendering text:** `H1`–`H6`, `P`, `Span`, `Div`, `Text` (with `as` prop)
 
-**Rendering content:** `Section` (Render + prose + layout), `Render` (ProseMirror → React), `ChildBlocks` (render child sections)
+**Rendering content:** `Section` (full section with prose + layout), `Article` (prose content from `block.rawContent`), `Render` (ProseMirror nodes → React), `ChildBlocks` (render child sections)
 
 **Rendering media:** `Visual` (first non-empty: inset/video/image), `Image`, `Media`, `Icon`
 
@@ -867,15 +896,20 @@ useColorContext(block) → 'light' | 'medium' | 'dark'   // current section cont
 
 ### Icon Component
 
-The `<Icon>` renders icons from content or explicit props. The simplest usage — spread an icon object from content:
+The `<Icon>` renders icons from content or explicit props:
 
 ```jsx
-{content.icons.map((icon, i) => <Icon key={i} {...icon} />)}
+{content.icons.map((icon, i) => <Icon key={i} {...icon} />)}   // From content
+<Icon name="search" />                                          // Lucide (default)
+<Icon name="hi2-arrow-right" />                                 // Other library
+<Icon name="close" />                                           // Built-in (no network)
 ```
 
-Props: `library` + `name` (from content), `svg` (direct SVG string), `url` (fetch from URL), `size` (default `'24'`), `className`. The legacy `icon` prop accepts shorthand strings (`"lu-house"`) or objects.
+The `name` prop handles everything: built-in names, Lucide icons (default when no library prefix), and other libraries via prefix (`hi2-arrow-right`, `tb-star`). From content, spread the icon object which has `library` + `name` fields.
+
+Other props: `svg` (direct SVG string), `url` (fetch from URL), `size` (default `'24'`), `className`.
 
-Built-in icons (no library needed): `check`, `close`, `menu`, `chevronDown`, `chevronRight`, `externalLink`, `download`, `play`, and a few others.
+Built-in icons (instant, no network): `check`, `close`, `menu`, `chevronDown`, `chevronRight`, `externalLink`, `download`, `play`, and a few others.
 
 ### Content Patterns for Header and Footer
 

package/src/index.js

@@ -727,19 +727,32 @@ async function main() {
 
   // Initialize git repository
   if (!noGit) {
+    // Skip git init if already inside a git repo (common for monorepos/workspaces)
+    let insideGitRepo = false
     try {
-      execSync('git --version', { stdio: 'ignore' })
+      execSync('git rev-parse --is-inside-work-tree', { cwd: projectDir, stdio: 'ignore' })
+      insideGitRepo = true
+    } catch {
+      // Not inside a git repo — proceed with init
+    }
+
+    if (insideGitRepo) {
+      log(`  ${colors.dim}Skipping git init — already inside a git repository${colors.reset}`)
+    } else {
       try {
-        execSync('git init', { cwd: projectDir, stdio: 'ignore' })
-        execSync('git add -A', { cwd: projectDir, stdio: 'ignore' })
-        execSync('git commit -m "Initial commit from uniweb"', { cwd: projectDir, stdio: 'ignore' })
-        success('Git repository initialized')
+        execSync('git --version', { stdio: 'ignore' })
+        try {
+          execSync('git init', { cwd: projectDir, stdio: 'ignore' })
+          execSync('git add -A', { cwd: projectDir, stdio: 'ignore' })
+          execSync('git commit -m "Initial commit from uniweb"', { cwd: projectDir, stdio: 'ignore' })
+          success('Git repository initialized')
+        } catch {
+          log(`  ${colors.yellow}Warning: Git repository initialized but initial commit failed${colors.reset}`)
+          log(`  ${colors.dim}Run 'git commit -m "Initial commit"' after configuring git${colors.reset}`)
+        }
       } catch {
-        log(`  ${colors.yellow}Warning: Git repository initialized but initial commit failed${colors.reset}`)
-        log(`  ${colors.dim}Run 'git commit -m "Initial commit"' after configuring git${colors.reset}`)
+        // git not available — skip silently
       }
-    } catch {
-      // git not available — skip silently
     }
   }