MarkUpDown Design Spec

The
MUD Language

Three primitives. No proprietary binary. No React island required for a hero band. MUD = structured markup humans and AI can agree on.

File format

Every page is pagename.mud with YAML frontmatter (title, menu, format: mud-spec, process: markdown: false).

Opens a page-level design context (theme name, layout mode, optional CSS variables).

Named blocks: hero, cards, pricing, timeline, compare, code, manifesto, and more.

Structured config inside fences — lists, nested keys, multiline bodies with |.

Grav discovers .mud via the grav-mud-alpha plugin (onPluginsInitialized registers the extension before page scan).

Extension competes with .md by priority — .mud wins when both exist in a folder.

mud

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

::: hero
eyebrow: Hello
title: Grav
accent: MUD
lead: One file. Full section.
cta:
  - [Go](/) primary
:::

Copy this into user/pages/01.home/default.mud and clear Grav cache. Done.

Promo landing patterns — CTAs use markdown link syntax with optional primary suffix.

Agency tier cards with plan: blocks, feature lists, and highlight flag. Built for the Services page.

Roadmaps and before/after tables without hand-rolling HTML tables in Twig.

Fenced samples for docs — escaped pre blocks, language label, optional caption.

Plain .mdGrav MUD (.mud)

Free-form prose onlyDeclared layout sections

Theme guesses structureCompiler emits semantic HTML

AI edits break TwigAI edits fenced blocks

".md cosplay"Real .mud extension