Press Typography — Syntax Guide
The ::syntax system provides simple, readable notation for designing complex layouts directly in your Markdown files. Inspired by Obsidian’s callout syntax and MDX component patterns, it bridges plain text and advanced HTML structures.
Philosophy
“Markup should be readable by humans, not just machines.” — Tim Berners-Lee
The ::syntax system rests on three principles:
- Minimal — Change as few lines as possible to get rich layouts.
- Readable — Patterns are self-documenting and intuitive.
- Composable — Structures can be nested and combined naturally.
Pattern Types
1. Smart Paragraphs
Single-line directives that automatically apply to the following paragraph (no need for ::end).
::hero
This paragraph will display with hero-sized typography (very large).
Live
This paragraph will display with hero-sized typography (very large).
Available:
::hero— Hero-sized paragraph (very large).::full— Paragraph spanning full width.::feature— Feature-sized paragraph (large).::editorial— Literary or editorial typographic style.::excerpt— Excerpt or summary paragraph.::card— Wraps the following element in a card.
2. Inline Directives
Short directives applying on a single line with immediate content.
::note This is an important reminder for later.
Live
Available:
::note— Note in aside.::alert— General alert.::warning— Warning alert.::error— Error alert.::success— Success alert.::muted— Muted text paragraph.::subtle— Subtle text paragraph.::space small|medium|large|xlarge— Proportional vertical spacing.::screen [full]— Screen transition separator (space-navigation stop).::download [label]— Download button for the note.::video [url]— Adaptive video player for YouTube, Vimeo, or native video.
3. Complex Blocks
Multi-line containers delimited by an opening directive and a ::end line. Ideal for complex layouts.
::callout tip
This is a very useful tip that can span multiple lines.
You can use **Markdown** inside.
::end
Live
This is a very useful tip that can span multiple lines.
You can use Markdown inside.
Built-in Blocks
Callouts (Obsidian Style)
::callout note
Standard callout with note styling.
::end
::callout + tip
Expandable callout open by default (+ indicator).
::end
::callout - warning
Expandable callout closed by default (- indicator).
::end
Live
Standard callout with note styling.
Tip
Expandable callout open by default (+ indicator).
Warning
Expandable callout closed by default (- indicator).
Supported Callout Types:
note(📝) — General notestip(💡) — Helpful tipsinfo(ℹ️) — Informationwarning(⚠️) — Warningsdanger(⚡) — Dangers / criticalssuccess(✅) — Success messagesquestion(❓) — Questionsquote(💬) — Quotationsabstract(📋) — Summariesbug(🐛) — Bug reportsexample(📄) — Examplesfailure(❌) — Failurestodo(☑️) — Todo lists
Layout Blocks (Grids and Columns)
Use --- separators on their own line to divide block content into multiple columns or cells.
Equal Columns (::columns)
::columns 2
Content of the left column.
---
Content of the right column.
::end
Live
Content of the left column.
Content of the right column.
Card Grid (::cards)
::cards
### Card 1
Description of the first card.
---
### Card 2
Description of the second card.
---
### Card 3
Description of the third card.
::end
Live
Card 1
Description of the first card.
Card 2
Description of the second card.
Card 3
Description of the third card.
Generic Grid (::grid)
::grid
First grid element.
---
Second grid element.
---
Third grid element.
::end
Live
First grid element.
Second grid element.
Third grid element.
Asymmetric Layout (::split)
::split 8/4
Main content (takes 8/12 of the width).
---
Sidebar (takes 4/12 of the width).
::end
Live
Main content (takes 8/12 of the width).
Sidebar (takes 4/12 of the width).
Screen Section (::screen)
Divide long articles, presentations, or photo essays into distinct screens:
::screen
### Section on this screen
Text and visuals.
::end
Or full viewport screens:
::screen full
# Immersive Opening
Visual photo story content.
::end
Image Gallery
::gallery
https://images.unsplash.com/photo-1
---
https://images.unsplash.com/photo-2
::end
Clickable Buttons
::button primary
[Visit the site](https://standard.garden)
::end
Live
Form Preview
::form contact
Full name
Email
Your message
::end
Live
Documenting syntax
To show a pattern in documentation, put it in a code fence — the pattern is not processed there, so the source appears exactly as written:
::callout Tip
Shown as text, not rendered.
::end
To show the source and the live result, use an example fence. The body appears first as code, then rendered under a Live label:
::callout Tip
This one is rendered for real, right below its own source.
::end
Live
This one is rendered for real, right below its own source.
An example body can contain any pattern, including blocks with their own ::end, because the fence keeps it opaque until Press expands it. Headings inside an example render as real headings but are left out of the page’s table of contents (stripLiveExamples in @stnd/press). Prefer ## and below, so the page keeps a single h1.
App-declared patterns
Press ships the built-in patterns above. A pattern that only means something to one app — say ::feed, which only stnd.gd can resolve — is declared by that app, not by Press. Put it in the module’s index.module.js:
export default {
id: "my-module",
press: {
patterns: {
stamp: {
type: "inline", // smart | inline | standalone | block | dual
priority: 40,
handler: (match) =>
match.context.preserve(`<div class="stamp">${match.value}</div>`, true),
},
},
},
};
Press collects these from virtual:stnd/modules (instances, which keeps the functions — virtual:stnd/config is JSON and would drop them) and merges them over the built-ins; same name, the app wins. A single Press can also take them directly: new Press(md, { patterns }).
A pattern still emits only HTML. If it must become a real component, the app resolves its placeholder afterwards (as stnd.gd does for ::feed).
Technical Integration
- Location: engine in
packages/press/typography/syntax.js, built-in patterns inpackages/press/typography/patterns/ - Stage:
pre(runs before markdown parsing) - Obsidian Rendering:
apps/stnd-obsidian/src/features/syntax-preview/index.js