Quickfix
Cheat sheets for all directives, modifiers, and fixes for common formatting mistakes.
Quick references for every directive, option, and inline element, followed by solutions for common mistakes.
Cheat sheet
Directives & blocks
| Directive | Purpose | Example syntax | Details |
|---|---|---|---|
| :::note / :::tip / :::warning / :::success | Callout & aside boxes | :::tip{title="Pro tip"} ... ::: | Asides & links |
| :::takeaways | Key points summary box | :::takeaways ... ::: | Asides & links |
| :::quote | Stylized pull-quote or quote | :::quote{author="Author"} ... ::: | Asides & links |
| :::cta | Call to action card | :::cta ... [Link](url) ::: | Asides & links |
| :::figure | Image with caption & sizing | :::figure{caption="..."}  ::: | Visuals |
| :::browser | Web page browser mockup | :::browser{caption="url"}  ::: | Visuals |
| :::video | Responsive video player | :::video{caption="..."} url ::: | Visuals |
| :::cartoon | Single or multi-panel cartoon | :::cartoon{layout="2-panel"} ... ::: | Visuals |
| :::table | CSV table (first row is the header) | :::table{wide} Plan, Price ... ::: | Visuals |
| :::mermaid | Text-to-diagram flowcharts | :::mermaid{caption="..."} flowchart LR ... ::: | Visuals |
| :::cards | Visual grid of link cards | :::cards - [Title](url): Desc ::: | Layout |
| ::::row + :::col | Multi-column responsive layout | ::::row :::col ... ::: :::col ... ::: :::: | Layout |
| :::steps | Sequenced instructional steps | :::steps 1. ... 2. ... ::: | Writing |
| - | Status list with visual marks | - ... - ... - ... | Writing |
| :::faq | Collapsible accordion questions | :::faq ### Q1 ... ### Q2 ... ::: | Writing |
| :::snippet | Centralized reusable component | :::snippet{name="newsletter"} ::: | Visuals |
Modifiers & dimensions
| Modifier | Applies to | Effect | Example |
|---|---|---|---|
| {wide} | Blocks figures tables diagrams | Breaks out +12rem beyond reading column | :::figure{wide} |
| {wider} | Cards notes tables | Stretches wider to align with outer sidebar edge | :::cards{wider} |
| {full} | Figures breakout banners | Stretches edge-to-edge across full screen | :::figure{full} |
| {side} | Callouts figures CTAs | Floats into sidebar track on desktop | :::note{side} |
| {side pinned} | Callouts figures CTAs | Sticks to viewport as reader scrolls section | :::tip{side pinned} |
| {w-*} | Figures diagrams tables | Constrains width in px rem or % (e.g. w-380) | :::figure{w-380} |
| {h-*} | Diagrams figures video | Constrains height with internal scroll (e.g. h-260) | :::mermaid{h-260} |
| {framed} | Figures screenshots | Adds subtle border and drop shadow | :::figure{framed} |
| title=... / caption=... | Any directive | Adds heading (top) or caption (bottom) interchangeably | {title="Headline"} |
Inline elements & badges
| Syntax | Result | Usage example |
|---|---|---|
| [Text](url){button} | Primary button | Start free trial{button} |
| [Text](url){button secondary} | Muted secondary button | View pricing{button secondary} |
| [Text](url){button arrow} | Primary button with trailing arrow | Get started{button arrow} |
| [Text](url) | Text link with trailing arrow | Read full case study |
| [Text](url){follow} | External link without nofollow (other sites are nofollow + new tab by default) | WPML{follow} |
| [Text](url){sponsored} | Paid or affiliate link: rel sponsored | Get the deal{sponsored} |
| Green check badge | Instant setup: | |
| Red cross badge | Hidden setup fees: | |
| Amber partial badge | Custom domains: | |
| / / | Grey dash badge (not applicable) | Phone support: |
| ==highlight== | Yellow text highlight | ==critical step== |
Troubleshooting
The rest of my post disappeared into a box
Why: A directive was opened with ::: but never closed. Everything after that line was swallowed into the box.
Fix: Add a closing ::: on its own line where the box should end:
:::tip
This tip is done.
:::
Normal paragraph following the box.My columns broke or a box closed too early
Why: Nested directives need different numbers of colons. If both use :::, the first closing tag closes the outer box early.
Fix: Use one more colon on the outer container (:::: around :::):
::::row
:::col
Column 1
:::
:::col
Column 2
:::
::::My box shows up as plain text with colons (:::)
Why: Markdown directives require a blank line before and after them. Without a blank line, Markdown treats them as regular sentences.
Fix: Add a blank line before ::: and after :::.
Previous paragraph.
:::note
This is properly parsed as a callout box.
:::
Next paragraph.The build failed on my title in frontmatter
Why: A frontmatter line contains a colon : inside the text (for example title: Guide: How to send), which confuses the YAML parser.
Fix: Wrap the entire value in double quotes:
title: "Guide: How to Send Bulk Emails Fast"My image is missing or broken
Why: The image path uses relative notation like ../media/pic.webp or media/pic.webp.
Fix: Always use an absolute path starting with /, matching the site’s media directory:
A box has a grey border and looks unstyled
Why: The directive name is misspelt or doesn’t exist.
Live preview:
Fix: Check your spelling against the Asides & links, Visuals, or Layout menus (e.g. :::tip, :::note, :::warning).
My FAQ didn’t turn into questions
Why: Questions inside a :::faq block must use level 3 headings (###), not ## or bold text.
Fix: Use ### for each question:
:::faq
### How do I reset my password?
Click the "Forgot password" link on the login screen.
### Can I change my email address?
Yes, visit Account Settings > Profile.
:::My button shows {button} as literal text
Why: There is a space between the link’s closing parenthesis ) and {button}.
Fix: Make sure they touch with zero whitespace:
<!-- Wrong: shows as link followed by "{button}" -->
[Sign Up](https://example.com/) {button}
<!-- Correct: turns into a button -->
[Sign Up](https://example.com/){button}