MUD GRAV MUD Alpha · Human/AI Design Language
Grav MUD Services

MARKUPDOWN SPECIFICATION

MUD-SPEC
v0.5 Alpha

Every component below shows .mud source beside its HTML output — the same compiler pipeline on every Grav page. Built for humans, agents, and anyone tired of Twig soup.

Language introCode Designer MUD-SPECGet Started

Contents

1. Design principles

  • Plain text first — diff-friendly, Git-native, agent-editable.
  • Two block families — presentation (:::) vs execution (++ … :::). Do not mix semantics.
  • Component-aware — fences map to semantic HTML regions and theme CSS.
  • Deployed realities — Grav discovers .mud via grav-mud-alpha; no .md cosplay required.

2. Block families

  • Design tokens — @@@ … @@@ — page theme name, layout mode, optional CSS variables
  • Layout fences — ::: type … ::: — hero, cards, pricing, docs blocks
  • NEXT Object Notation — ++ label … ::: — structured config (hubs, ports, nested keys)
  • Spec examples — ::: example — this page: source + live HTML preview

3. Grav frontmatter

Every page is default.mud (or pagename.mud) with YAML frontmatter:

  • format: mud-spec — theme body class + compiler path
  • process.markdown: false — Grav must not re-parse compiled HTML
  • process.twig: true — optional Twig in frontmatter only

See Language for a gentler intro; this page is the full component catalog.

4. Design tokens (@@@)

cmp-tokens

Page-level design context

Opens the .mud-page wrapper with data-mud-layout. This spec page uses layout: spec-doc for wide example columns.

.mud source
@@@
name: grav-official
layout: spec-doc
@@@

::: hero
mascot: none
eyebrow: Tokens active
title: Layout
accent: spec-doc
lead: The compiler wraps all following fences until the page ends.
:::
HTML output

Tokens active

Layout
spec-doc

The compiler wraps all following fences until the page ends.

Use layout: promo on marketing pages; spec-doc on reference docs like this one.

5. hero

cmp-hero

Promo hero band

Eyebrow, split title + accent, lead (markdown), CTA links. Set mascot: none on light Grav themes.

.mud source
@@@
name: grav-official
layout: promo
@@@

::: hero
mascot: none
eyebrow: Grav MUD (Alpha)
title: Human/AI
accent: Design Language
lead: One `.mud` file. Full landing section. Zero template soup.
cta:
  - [MUD Spec](/spec) primary
  - [Services](/services)
:::
HTML output

Grav MUD (Alpha)

Human/AI
Design Language

One .mud file. Full landing section. Zero template soup.

MUD SpecServices

6. quote

cmp-quote

Pull quote

Blockquote with cite and optional footnote.

.mud source
@@@
name: grav-official
layout: promo
@@@

::: quote
quote: "Markdown told you what to say. MUD tells Grav how to show it."
cite: — Team DC, FutureVision Labs
note: PoC / pitch fork. Not an official Grav Core release. Yet.
:::
HTML output
"Markdown told you what to say. MUD tells Grav how to show it."
— Team DC, FutureVision Labs

PoC / pitch fork. Not an official Grav Core release. Yet.

7. cards

cmp-cards

Card grid

Repeat card: blocks with title and body (markdown).

.mud source
@@@
name: grav-official
layout: promo
@@@

::: cards
title: Why fences exist
card:
  title: Declared structure
  body: Sections are named — not guessed from H2 soup.
card:
  title: AI-safe edits
  body: Agents patch `::: hero` blocks without touching Twig.
card:
  title: Real `.mud`
  body: Registered before Grav page scan — not renamed Markdown.
:::
HTML output

Why fences exist

Declared structure

Sections are named — not guessed from H2 soup.

AI-safe edits

Agents patch ::: hero blocks without touching Twig.

Real .mud

Registered before Grav page scan — not renamed Markdown.

8. timeline

cmp-timeline

Roadmap / changelog

event: blocks with date and text.

.mud source
@@@
name: grav-official
layout: promo
@@@

::: timeline
title: Alpha roadmap
event:
  date: Now
  text: Flagship gravmud.site, Services pricing, this MUD-SPEC page.
event:
  date: Next
  text: Admin blueprint, Flex parity, shared parser with Code Designer.
:::
HTML output

Alpha roadmap

  1. Flagship gravmud.site, Services pricing, this MUD-SPEC page.

  2. Admin blueprint, Flex parity, shared parser with Code Designer.

9. compare

cmp-compare

Before / after table

row: blocks with left, right, optional highlight: true.

.mud source
@@@
name: grav-official
layout: promo
@@@

::: compare
title: MUD vs plain Markdown
left: Plain .md
right: Grav MUD (.mud)
row:
  left: Free-form prose only
  right: Declared layout sections
row:
  left: Theme guesses structure
  right: Compiler emits semantic HTML
row:
  left: ".md cosplay"
  right: Real `.mud` extension
  highlight: true
:::
HTML output

MUD vs plain Markdown

Plain .mdGrav MUD (.mud)
Free-form prose onlyDeclared layout sections
Theme guesses structureCompiler emits semantic HTML
".md cosplay"Real .mud extension

10. pricing

cmp-pricing

Agency tier cards

plan: blocks with price, features (list), highlight, and CTA link.

.mud source
@@@
name: grav-official
layout: promo
@@@

::: pricing
title: Grav MUD Services (sample)
plan:
  name: MUD Seed
  price: from $149
  features:
    - Single landing `.mud`
    - Theme wiring
  cta: [Contact](/get-started)
plan:
  name: MUD Studio
  price: from $449
  highlight: true
  features:
    - Multi-page site
    - Spec + Services blocks
  cta: [Contact](/get-started) primary
:::
HTML output

Grav MUD Services (sample)

MUD Seed

from $149

MUD Studio

from $449

11. code

cmp-code

Documentation code sample

Escaped pre block with optional lang and caption.

.mud source
::: code
title: Minimal page
lang: mud
body: |
  @@@
  name: grav-official
  layout: promo
  @@@

  ::: hero
  title: Hello
  accent: MUD
  :::
caption: Copy into user/pages/…/default.mud and clear Grav cache.
:::
HTML output

Minimal page

mud
@@@
name: grav-official
layout: promo
@@@

::: hero
title: Hello
accent: MUD
:::

Copy into user/pages/…/default.mud and clear Grav cache.

12. callout

cmp-callout

Legacy doc callout

Short-form fence — variant as second token on the opening line.

.mud source
@@@
name: grav-official
layout: promo
@@@

::: callout note
Grav MUD Alpha still supports legacy **callout** fences alongside Design Spec blocks. Variants: note, warn, tip.
:::
HTML output

13. manifesto

cmp-manifesto

Closing pitch block

Title + multiline body: with | and HTML signoff.

.mud source
@@@
name: grav-official
layout: promo
@@@

::: manifesto
title: One paragraph pitch
body: |
  Grav won by staying flat and fast. **Grav MUD** adds a design language layer without becoming a page-builder monolith — content stays text, layouts stay declared, themes stay CSS.
signoff: <strong>Grav MUD (Alpha)</strong> · <a href="/get-started">Get started</a>
:::
HTML output

One paragraph pitch

Grav won by staying flat and fast. Grav MUD adds a design language layer without becoming a page-builder monolith — content stays text, layouts stay declared, themes stay CSS.

Grav MUD (Alpha) · Get started

14. The ::: example fence

This entire reference page is built from ::: example blocks. Each entry declares:

  • title — human label
  • id — anchor for the table of contents
  • desc — short explanation
  • body: | — the .mud snippet to compile for the preview panel
  • caption — optional footnote

The compiler recursively runs body through the same pipeline as a full page (auto-wrapping @@@ grav-official when omitted).

15. Version

  • v0.5 Alpha — Grav flagship site, example fence, MUD-SPEC page, halved Services pricing
  • v0.3 — Design Spec fences, @@@ tokens, grav-mud-site theme
  • Code Designer MUD-SPEC v0.1 — TS parser + export pipeline reference

Ship it

You wanted comprehensive. You got source | output on every fence that matters for gravmud.site. Paste a block into your .mud, clear cache, done.

Questions? Get Started · Grav MUD Services

Powered by Grav MUD Alpha v0.5.0 · MarkUpDown Design Spec (.mud) · NEXT Object Notation