# MarkUpDown (.mud) Specification

> **Canonical web version:** [mud-spec.html](mud-spec.html) — full spec with live HTML output examples.  
> This file is the portable markdown source for repos and CeeDee training manifests.

**Version:** 0.1 (Team DC · FutureVision Labs)  
**File extension:** `.mud`  
**Syntax families:** `:::` render fences · `++` executable blocks

MarkUpDown is a markdown-like notation for documentation, microsites, magazines, and code-adjacent canon. It exports to HTML, PDF, and generated source. Code Designer is the reference implementation.

---

## 1. Design principles

1. **Plain text first** — diff-friendly, Git-native, CeeDee-trainable.
2. **Two block families** — presentation (`:::`) vs execution (`++`). Never mix semantics.
3. **Component-aware** — blocks map to HTML regions, CURSY classes, and export targets.
4. **Deployed realities only** — examples reference live `.live` properties where possible.

---

## 2. Core markdown (baseline)

Compatible with familiar markdown unless noted.

| Construct | Syntax |
|-----------|--------|
| Title | `# H1` |
| Section | `## H2` … `###### H6` |
| Bold | `**text**` |
| Emphasis | `*text*` |
| Link | `[label](url)` |
| List | `- item` or `1. item` |
| Blockquote | `> quote` |
| Inline code | `` `code` `` |
| Horizontal rule | `---` |

Headings receive auto-slugs for anchor links and ToC generation.

---

## 3. Block families

### 3.1 Render fences — `:::`

Fenced **presentation components**. Open with `::: type`, optional attributes on the same line, body until closing `:::`.

```mud
::: hero
title: Mud Pies
subtitle: Bake your first .mud file
:::
```

**Rules:**

- Opening fence: `::: <type> [key=value ...]`
- Closing fence: `:::` alone on its own line
- Body: key-value lines, markdown, or nested `:::` blocks
- Attributes may use `key=value` on the opening line: `::: grid columns=3 gap=1.5rem`

### 3.2 Executable blocks — `++`

Fenced **generative** content — code, config, N.O.N., export manifests. Not layout.

```mud
++ N.O.N. hub config
hub
    name "FutureVision Live"
    port 3000
```

**Rules:**

- Opens with `++ <label>` (label is human-readable, optional for parser hints)
- Closes at next `++`, heading of equal/higher level, or `:::`
- Exported to files when an `export` manifest is present

---

## 4. Document frontmatter

Optional metadata block at file top, delimited by `---` or a `::: meta` fence.

```mud
---
title: SexBox.Live Launch Canon
description: Hardware manifest and network ring
og_image: assets/markupdown-hero.png
export:
  html: dist/canon.html
  pdf: print/canon.pdf
theme: cursy-dark
---
```

| Key | Purpose |
|-----|---------|
| `title` | Page title, `<title>`, og:title |
| `description` | Meta description |
| `og_image` | Social preview image |
| `export` | html / pdf / code output paths |
| `theme` | CURSY theme token set |
| `toc` | `true` / `false` — auto-insert ToC |
| `nav` | Path to shared nav partial |

---

## 5. Render components (`:::`)

### 5.1 `hero`

Page opener — eyebrow, title, subtitle, CTAs, optional image.

```mud
::: hero
eyebrow: MARKUPDOWN TUTORIAL
title: Mud Pies
subtitle: Bake your first .mud file
image: assets/markupdown-hero.png
image_alt: MarkUpDown workflow
cta:
  - [Learn More](about.html#mud)
  - [Join Waitlist](waitlist.html) primary
:::
```

| Field | Required | Notes |
|-------|----------|-------|
| `title` | yes | Main headline |
| `subtitle` | no | Supporting line |
| `eyebrow` | no | Small label above title |
| `image` | no | Hero image path or URL |
| `image_alt` | no | Accessibility text |
| `cta` | no | List of `[label](url)`; suffix `primary` for emphasis button |

**Export:** `<section class="mud-hero">` + CURSY hero pattern.

---

### 5.2 `grid`

Flexbox / CSS grid layout container.

```mud
::: grid columns=3 gap=1.5rem responsive
::: card
icon: 🥧
title: Pie 01
body: Your first .mud file
:::
::: card
icon: ⚡
title: Pie 02
body: Headers and structure
:::
::: card
icon: 🚀
title: Pie 03
body: The ++ code block
:::
:::
```

| Attribute | Default | Values |
|-----------|---------|--------|
| `columns` | `1` | `1`–`6` or `auto` |
| `gap` | `1rem` | CSS length |
| `responsive` | — | presence flag: stack on mobile |
| `align` | `stretch` | `start` `center` `end` |

Children: typically `card`, raw markdown, or nested blocks.

---

### 5.3 `card`

Grid child or standalone feature tile.

```mud
::: card
icon: 🛡️
title: SoftRadix QA
body: Komal Garg team — FVLive + FlipZine beta scope
link: [Brief](partner-brief.mud)
:::
```

| Field | Notes |
|-------|-------|
| `icon` | Emoji or image URL |
| `title` | Card heading |
| `body` | Markdown body |
| `link` | Optional footer link |

---

### 5.4 `toc`

Table of contents from document headings.

```mud
::: toc depth=3 sticky
:::
```

| Attribute | Default | Notes |
|-----------|---------|-------|
| `depth` | `3` | Max heading level (1–6) |
| `sticky` | off | Sidebar sticky nav |
| `title` | `Contents` | ToC heading |

Auto-links to `#slug` anchors. Omit block when `toc: true` in frontmatter (inserts after hero).

---

### 5.5 `embed`

Sandboxed HTML or iframe embed.

```mud
::: embed sandbox
src: https://homebrewz.live/play.html
height: 480
title: EmulatorJS Playground
:::
```

Raw HTML variant:

```mud
::: embed html
<div class="crt-viewport" data-system="c64">
  <!-- EmulatorJS mount -->
</div>
:::
```

| Attribute | Notes |
|-----------|-------|
| `src` | iframe URL (implies sandbox) |
| `height` | iframe height (default `400`) |
| `sandbox` | flag: enable iframe sandbox attrs |
| `html` | raw HTML body (sanitized subset in export) |
| `title` | accessible iframe title |

**Security:** Reference implementation strips scripts from `html` mode unless `trusted: true` in frontmatter.

---

### 5.6 `form`

Declarative contact / waitlist form.

```mud
::: form contact action=/api/waitlist method=POST
field name text label="Your name" required
field email email label="Email" required
field message textarea label="Feedback" rows=4
submit: Join Waitlist
success: You're on the list. Deployed realities only.
:::
```

| Attribute | Notes |
|-----------|-------|
| `action` | POST endpoint |
| `method` | `POST` (default) or `GET` |
| `contact` | preset field set (name, email, message) |
| `waitlist` | preset → Code Designer waitlist API |

**Field line:** `field <name> <type> [label="..."] [required] [rows=N]`

Types: `text`, `email`, `tel`, `textarea`, `select`, `checkbox`, `hidden`

---

### 5.7 `callout`

Admonition / alert box.

```mud
::: callout canon
**Deployed realities only.** Do not document vaporware in canon .mud files.
:::
```

Types: `note`, `tip`, `warning`, `canon`, `danger`

---

### 5.8 `cta`

Full-width call-to-action band.

```mud
::: cta
title: Ready to get muddy?
body: Join the Code Designer waitlist.
button: [Join Waitlist](waitlist.html) primary
:::
```

---

### 5.9 `media`

Image, video, or audio with caption.

```mud
::: media
src: assets/markupdown-hero.png
alt: MarkUpDown workflow
caption: Author once. Export everywhere.
aspect: 1/1
lazy: true
:::
```

---

### 5.10 `section`

Named layout band with theme variant.

```mud
::: section alt id=features
## Key Features
Content markdown here…
:::
```

Variants: `main`, `alt`, `dark`, `canon`

---

### 5.11 `include`

Transclusion of another `.mud` partial.

```mud
::: include
path: partials/network-ring.mud
:::
```

Or shorthand: `{{include partials/network-ring.mud}}`

---

### 5.12 `tabs` / `accordion`

```mud
::: tabs
tab: Hardware
- Raspberry Pi 5
- Chromium kiosk
tab: Network
- futurevision.live
- flipzine.live
:::

::: accordion
item: What is .mud?
MarkUpDown — documentation notation for Code Designer.
item: What is N.O.N.?
NEXT Object Notation — see n-o-n.space
:::
```

---

### 5.13 `marquee`

Scrolling ticker (SexBox / promo sites).

```mud
::: marquee speed=slow
SEXBOX.LIVE · HOMEBREWZ.LIVE · FLIPZINE.LIVE · FUTUREVISION.LIVE
:::
```

---

### 5.14 `table`

Enhanced spec matrix table.

```mud
::: table spec
| Row | Physical | Digital | Shield |
|-----|----------|---------|--------|
| SexBox | RPi 5 | Portal | SoftRadix QA |
| FlipZine | — | flipzine.live | Magazine sync |
:::
```

`spec` variant adds zebra striping and header stickiness on export.

---

### 5.15 `timeline`

Changelog / journal entries.

```mud
::: timeline
2026-05-23: Mud Pies tutorial + MUD-SPEC v0.1 HTML shipped
2026-05-22: CeeDee page live on codedesigner.cloud
1990: FutureVision Designs established
:::
```

---

### 5.16 `diagram`

Mermaid or ASCII architecture block.

```mud
::: diagram mermaid
graph LR
  mud[.mud source] --> html[HTML export]
  mud --> pdf[PDF export]
  mud --> code[Generated code]
:::
```

---

### 5.17 `nav`

Declarative page navigation.

```mud
::: nav
- [Home](index.html)
- [Mud Pies](mud-pies.html) active
- [Waitlist](waitlist.html) button
:::
```

---

### 5.18 `waitlist`

Preset form wired to Code Designer waitlist API.

```mud
::: waitlist
submit: Join Waitlist
:::
```

Equivalent to `::: form waitlist action=/api/waitlist.php method=POST` with standard fields.

---

### 5.19 `gallery`

Image grid with optional lightbox.

```mud
::: gallery columns=3
- assets/markupdown-hero.png | MarkUpDown
- assets/code-designer-icon.png | Code Designer
:::
```

---

### 5.20 `flip`

Two-page magazine spread (FlipZine export).

```mud
::: flip
left: |
  # Cover story
  Inspired Cafe pilot script
right: |
  ## Cast
  - Dr. D
  - Gemzy
:::
```

---

## 6. Executable blocks (`++`)

| Label hint | Typical export |
|------------|----------------|
| `N.O.N.` / `non` | `.non` file or embedded config |
| `systemd` | unit file |
| `export` | manifest (also valid in frontmatter) |
| `javascript` / `typescript` | generated source |
| `html` | partial template |
| `css` | stylesheet fragment |

```mud
++ export manifest
html "dist/page.html"
pdf  "print/page.pdf"
code "src/generated/"
```

---

## 7. N.O.N. bridge

Inline N.O.N. without a full `++` block:

```mud
::: non
hub
    name "FutureVision Live"
    port 3000
:::
```

Parsed as data, not layout. Pairs with [N.O.N. spec](https://n-o-n.space/).

---

## 8. Export pipeline

1. Parse frontmatter
2. Build AST (markdown + `:::` nodes + `++` nodes)
3. Resolve `include` / `{{include}}`
4. Render HTML (CURSY default theme)
5. Optional PDF via print stylesheet
6. Emit `++` blocks to paths in export manifest

---

## 9. Full page example

See [`examples/mud-pies-demo.mud`](examples/mud-pies-demo.mud).

---

## 10. Version history

| Version | Date | Notes |
|---------|------|-------|
| 0.1 | 2026-05-23 | Initial spec: `:::` fences, hero/grid/toc/embed/form, extended components; HTML page with output examples |

---

**FutureVision Labs · Team DC · Code Designer**  
Tutorial: [Mud Pies](mud-pies.html) · [MUD-SPEC (HTML)](mud-spec.html) · [codedesigner.cloud](https://codedesigner.cloud/)