Skip to content
PutlerPutlerSearch

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

DirectivePurposeExample syntaxDetails
:::note / :::tip / :::warning / :::successCallout & aside boxes:::tip{title="Pro tip"} ... :::Asides & links
:::takeawaysKey points summary box:::takeaways ... :::Asides & links
:::quoteStylized pull-quote or quote:::quote{author="Author"} ... :::Asides & links
:::ctaCall to action card:::cta ... [Link](url) :::Asides & links
:::figureImage with caption & sizing:::figure{caption="..."} ![Alt](url) :::Visuals
:::browserWeb page browser mockup:::browser{caption="url"} ![Alt](url) :::Visuals
:::videoResponsive video player:::video{caption="..."} url :::Visuals
:::cartoonSingle or multi-panel cartoon:::cartoon{layout="2-panel"} ... :::Visuals
:::tableCSV table (first row is the header):::table{wide} Plan, Price ... :::Visuals
:::mermaidText-to-diagram flowcharts:::mermaid{caption="..."} flowchart LR ... :::Visuals
:::cardsVisual grid of link cards:::cards - [Title](url): Desc :::Layout
::::row + :::colMulti-column responsive layout::::row :::col ... ::: :::col ... ::: ::::Layout
:::stepsSequenced instructional steps:::steps 1. ... 2. ... :::Writing
-Status list with visual marks- ... - ... - ...Writing
:::faqCollapsible accordion questions:::faq ### Q1 ... ### Q2 ... :::Writing
:::snippetCentralized reusable component:::snippet{name="newsletter"} :::Visuals

Modifiers & dimensions

ModifierApplies toEffectExample
{wide}Blocks figures tables diagramsBreaks out +12rem beyond reading column:::figure{wide}
{wider}Cards notes tablesStretches wider to align with outer sidebar edge:::cards{wider}
{full}Figures breakout bannersStretches edge-to-edge across full screen:::figure{full}
{side}Callouts figures CTAsFloats into sidebar track on desktop:::note{side}
{side pinned}Callouts figures CTAsSticks to viewport as reader scrolls section:::tip{side pinned}
{w-*}Figures diagrams tablesConstrains width in px rem or % (e.g. w-380):::figure{w-380}
{h-*}Diagrams figures videoConstrains height with internal scroll (e.g. h-260):::mermaid{h-260}
{framed}Figures screenshotsAdds subtle border and drop shadow:::figure{framed}
title=... / caption=...Any directiveAdds heading (top) or caption (bottom) interchangeably{title="Headline"}

Inline elements & badges

SyntaxResultUsage example
[Text](url){button}Primary buttonStart free trial{button}
[Text](url){button secondary}Muted secondary buttonView pricing{button secondary}
[Text](url){button arrow}Primary button with trailing arrowGet started{button arrow}
[Text](url)Text link with trailing arrowRead 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 sponsoredGet the deal{sponsored}
Green check badgeInstant setup:
Red cross badgeHidden setup fees:
Amber partial badgeCustom 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:

![Dashboard preview](/media/dashboard-preview.webp)

A box has a grey border and looks unstyled

Why: The directive name is misspelt or doesn’t exist.

Live preview:

This block was written as :::nonsense. Because “nonsense” is not a known block, Stoic preserves the words but shows this unstyled fallback box.

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}