feat: sidebar-main layout and fix grid detection inside containers

FAQ.md

@@ -105,13 +105,13 @@ Three ways:
 
 **Check these:**
 
-1. Grid class is on the parent heading: `## Title {.grid-3}`
+1. Grid class is on the parent heading: `## Title {.grid-3 card}`
 2. Grid items are `###` headings (one level deeper)
 3. Each grid item starts with `###`
 
 ```markdown
 ✅ Correct:
-## Features {.grid-3}
+## Features {.grid-3 card}
 
 ### Feature 1
 Content
@@ -120,7 +120,7 @@ Content
 Content
 
 ❌ Wrong (missing ### for items):
-## Features {.grid-3}
+## Features {.grid-3 card}
 Feature 1
 Feature 2
 ```
@@ -273,9 +273,9 @@ Use state attributes:
 ### What grid sizes are supported?
 
 Built-in grid classes:
-- `{.grid-2}` - 2 columns
-- `{.grid-3}` - 3 columns
-- `{.grid-4}` - 4 columns
+- `{.grid-2 card}` - 2 columns
+- `{.grid-3 card}` - 3 columns
+- `{.grid-4 card}` - 4 columns
 - `{.grid-auto}` - Auto-fit columns
 
 ### Can I nest containers?

QUICK-REFERENCE.md

@@ -19,7 +19,10 @@
 | **Radio** | `- ( )` / `- (*)` | `- (*) Option 1` |
 | **Icon** | `:name:` | `:home: :user: :gear:` |
 | **Nav Bar** | `[[ A \| B \| C ]]` | `[[ Home \| About \| [Login] ]]` |
+| **Nav Link** | `[[ [Text](url) \| ... ]]` | `[[ [About](./about.md) \| ... ]]` |
 | **Breadcrumbs** | `[[ A > B > C ]]` | `[[ Home > Products > Item ]]` |
+| **Button Link** | `[[Text](url)]` | `[[About](./about.md)]` |
+| **Primary Button Link** | `[[Text](url)]*` | `[[Get Started](./start.md)]*` |
 
 ## Containers
 
@@ -35,14 +38,18 @@
 
 ## Layouts
 
-| Layout | Syntax | Example |
-|--------|--------|---------|
-| **2-Column Grid** | `## Title {.grid-2}` | Section with 2 columns |
-| **3-Column Grid** | `## Title {.grid-3}` | Section with 3 columns |
-| **4-Column Grid** | `## Title {.grid-4}` | Section with 4 columns |
-| **Auto Grid** | `## Title {.grid-auto}` | Auto-fit columns |
+| Layout | Syntax | Notes |
+|--------|--------|-------|
+| **Grid (layout only)** | `## Title {.grid-3}` | Equal columns, no styling on items |
+| **Grid (card chrome)** | `## Title {.grid-3 card}` | Items rendered as styled cards |
+| **2-Column Grid** | `## Title {.grid-2}` | |
+| **3-Column Grid** | `## Title {.grid-3}` | |
+| **4-Column Grid** | `## Title {.grid-4}` | |
+| **Col span** | `### Item {.col-span-2}` | Item spans 2 columns |
 
-Grid items are defined by `###` headings under the grid heading.
+Grid items are defined by `###` headings under the grid heading. The grid heading label (e.g., "Features") is a **declaration-only** author comment — it is never rendered in the output.
+
+`{.grid-N}` is pure layout — use it for form columns, multi-column text, etc. Add `card` when items should have card chrome (features, pricing, team members).
 
 ## Attributes
 
@@ -128,10 +135,21 @@ Message
 [[ Home > Products > Category > Item ]]
 ```
 
+### Multi-file Navigation
+
+When running `wiremd --serve`, clicking a button link navigates to and renders that `.md` file:
+
+```markdown
+# Shared navbar (paste in each page)
+[[ :logo: MyApp | [Home](./home.md) | [About](./about.md) | [Contact](./contact.md)* ]]
+```
+
+The dev server (`--serve <port>`) redirects `/` to the entry file and renders any `.md` on demand — no build step needed between page navigations.
+
 ## Grid Pattern
 
 ```markdown
-## Features {.grid-3}
+## Features {.grid-3 card}
 
 ### Feature 1
 Description here
@@ -180,7 +198,7 @@ Password
 
 ### Stats Grid
 ```markdown
-## Metrics {.grid-4}
+## Metrics {.grid-4 card}
 
 ### Users
 10,000+

README.md

@@ -51,7 +51,7 @@ This renders into a styled HTML wireframe with a form, inputs, and buttons.
 Create a `features.md` file:
 
 ```markdown
-## Product Features {.grid-3}
+## Product Features {.grid-3 card}
 
 ### :rocket: Fast
 Lightning quick performance

SYNTAX-SPEC-v0.1.md

@@ -191,7 +191,7 @@ Content goes here
 ### 4.1 Grid Layouts
 
 ```markdown
-## Features {.grid-3}
+## Features {.grid-3 card}
 
 ### Feature One
 Content
@@ -489,7 +489,7 @@ We couldn't load this page
 | Class | `{.class}` | `{.primary}` |
 | Attribute | `{key:value}` | `{type:email}` |
 | State | `{:state}` | `{:disabled}` |
-| Grid | `{.grid-N}` | `{.grid-3}` |
+| Grid | `{.grid-N}` | `{.grid-3 card}` |
 
 ---
 
@@ -715,7 +715,7 @@ Email
 
 **Input:**
 ```markdown
-## Features {.grid-3}
+## Features {.grid-3 card}
 
 ### :rocket: Fast
 Quick rendering

docs/examples/index.md

@@ -60,7 +60,7 @@ Message
 ### Dashboard Layout
 
 ```markdown
-## Dashboard {.grid-3}
+## Dashboard {.grid-3 card}
 
 ### Active Users
 **1,234**
@@ -201,7 +201,7 @@ The best tool for modern teams to collaborate and build amazing products.
 ### Pricing Table
 
 ```markdown
-## Pricing {.grid-3}
+## Pricing {.grid-3 card}
 
 ### Basic
 **$9/month**

docs/guide/syntax.md

@@ -100,10 +100,26 @@ Try our product today
 
 ### Grid Layouts
 
-Create grids with heading modifiers:
+`{.grid-N}` on a heading creates an N-column layout. Child `###` headings become grid items. The heading label itself is **declaration-only** — it is never rendered in the output; it only names the grid for the author.
+
+**Pure layout grid** — no visual styling on items, useful for form columns or multi-column text:
 
 ```markdown
-## Features {.grid-3}
+## Contact {.grid-2}
+
+### Details
+Name
+[_____________________________]{required}
+
+### Address
+Street
+[_____________________________]{required}
+```
+
+**Card grid** — add `card` to render items with card chrome:
+
+```markdown
+## Features {.grid-3 card}
 
 ### Fast
 Lightning quick performance
@@ -115,6 +131,35 @@ Enterprise-grade security
 Grows with your needs
 ```
 
+### Button Links
+
+Wrap a Markdown link inside button brackets to make a clickable button that navigates:
+
+```markdown
+[[Go to Docs](./docs.md)]
+[[Get Started](./start.md)]*
+```
+
+The `*` suffix makes it a primary button. Attributes work too:
+
+```markdown
+[[Sign Up](./signup.md)]{.secondary}
+```
+
+When using `wiremd --serve`, clicking a button link renders the target `.md` file in the same browser tab — no build step required. This is the recommended way to wire up multi-page navigation in prototypes.
+
+**Column spanning** — `{.col-span-N}` on a child heading spans multiple columns:
+
+```markdown
+## Pricing {.grid-3 card}
+
+### Starter {.col-span-1}
+$9/mo
+
+### Pro {.col-span-2}
+$29/mo — most popular, spans two columns
+```
+
 ## Component Examples
 
 ### Forms

docs/guide/troubleshooting.md

@@ -78,14 +78,14 @@ try {
 **Problem**: Grid syntax doesn't create columns
 
 ```markdown
-## Features {.grid-3}
+## Features {.grid-3 card}
 Content here...
 ```
 
 **Solution**: Ensure proper structure with level-3 headings:
 
 ```markdown
-## Features {.grid-3}
+## Features {.grid-3 card}
 
 ### Column 1
 Content for column 1
@@ -448,8 +448,8 @@ Common validation errors and fixes:
 
 // Error: INVALID_GRID_COLUMNS
 // Fix: Use 1 or more columns
-{.grid-3}            // ✓ Valid
-{.grid-0}            // ✗ Invalid
+{.grid-3 card}            // ✓ Valid
+{.grid-0 card}            // ✗ Invalid
 ```
 
 ## Performance Issues

examples/figma-test.md

@@ -16,7 +16,7 @@ This mockup demonstrates all wiremd features that can be imported to Figma.
 
 ---
 
-## Features Grid {.grid-3}
+## Features Grid {.grid-3 card}
 
 ### ⚡ Fast
 Lightning-quick wireframing with markdown syntax

examples/gallery/README.md

@@ -60,6 +60,22 @@ Application dashboards for data visualization and management.
 
 ---
 
+### 🔗 Multi-Page Navigation (1 Example)
+
+A three-page prototype showing how button links and the dev server work together for real navigation.
+
+| Example | Description | Key Features |
+|---------|-------------|--------------|
+| **Multi-Page App** | Home → About → Contact prototype | Shared navbar, button links, live navigation between pages |
+
+**Run it:**
+```bash
+wiremd examples/gallery/multi-page/home.md --serve 3001
+# Open http://localhost:3001 and click the nav buttons
+```
+
+---
+
 ### 🧩 Components (5 Examples)
 
 Reusable UI component patterns and layouts.