Skip to content
PutlerPutlerSearch

Visuals, tables & snippets

Blocks that show something: pictures, video, diagrams, tables, and reusable snippets.

Picture

Use when: Images, figures, and UI captures.

A talk in progress

From Meh to Memorable
:::figure{caption="From Meh to Memorable"}
![A talk in progress](/test-assets/talk-meh-to-memorable.webp)
:::
Screenshots that look professional
  • Crop tight: remove empty margins, desktop borders, and dead screen space.
  • Use realistic data: use real customer names and product numbers, not “asdf” or “test”.
  • Hide clutter: turn off browser bookmarks, extension icons, and OS notifications.
  • Don’t leave empty space: collapse unused sidebars and resize windows to fit the content.
  • Save retina captures as name@2x.webp: rendered at half size so text stays sharp.
  • Frame white UI: add {framed} or use :::browser so light UI does not bleed into the page.
Do and don't

Do: always write descriptive alt text and a helpful caption. Don’t: upload uncompressed PNGs straight from your screenshot tool.

Browser window

Use when: Show web pages in a realistic browser frame.

Creating a Buy Now link in WooCommerce
https://example.com/checkout
:::browser{caption="https://example.com/checkout"}
![Creating a Buy Now link in WooCommerce](/test-assets/create-buy-now-link.webp)
:::
Do and don't

Do: include the URL in the caption attribute. Don’t: use a browser frame for mobile app screenshots.

Video

Use when: Responsive video players and looping clips.

WooCommerce checkout walk-through
WooCommerce checkout walk-through
:::video{caption="WooCommerce checkout walk-through"}
https://www.youtube.com/watch?v=dQw4w9WgXcQ
:::

Paste a YouTube URL or a path to a self-hosted MP4. YouTube videos automatically fetch and display their video cover image. For self-hosted videos, specify poster="/path/to/poster.jpg".

Do and don't

Do: use silent looping MP4s instead of animated GIFs. Don’t: enable sound autoplay on page load.

Cartoon

Use when: A comic panel placed beside text in the sidebar.

Black Friday cartoon

The quickest way to double your sales is to halve your prices.
:::cartoon{caption="The quickest way to double your sales is to halve your prices."}
![Black Friday cartoon](/test-assets/black-friday-cartoon@2x.webp)
:::

A square comic panel with its punchline underneath. It always goes in the sidebar, beside the text you put it next to. On phones there is no sidebar, so it sits in the text where you placed it.

Use it for a light break beside a dense section. Never make it carry information the reader needs; plenty of readers will skip it. One per post.

Do and don't

Do: keep the punchline short and self-contained. Don’t: put essential diagrams or technical charts in a cartoon box.

Diagram

Use when: Flowcharts and sequence diagrams from text.

Yes

No

Cart Abandoned

Email Sent?

Customer Returns

Send 1hr Reminder

Checkout recovery workflow
:::mermaid{caption="Checkout recovery workflow"}
flowchart LR
  A[Cart Abandoned] --> B{Email Sent?}
  B -- Yes --> C[Customer Returns]
  B -- No --> D[Send 1hr Reminder]
  D --> C
:::

Draw a diagram by writing text. Each line is one arrow: A[Customer] --> B[Checkout]. It’s turned into a crisp picture when the site builds.

Easiest way: open mermaid.live, start from one of the examples below, change the words, and watch the picture update. Paste the text back between :::mermaid and :::.

Keep it small: more than about ten boxes is two diagrams.

Do and don't

Do: keep diagrams under ten boxes so text remains readable. Don’t: put large software architecture schemas in a single diagram.

Table

Use when: Structured data, prices, and feature comparisons.

FeatureStarterBusinessEnterprise
Monthly recovery emails5005000Unlimited
Custom sender domain
Priority live support
:::table
Feature, Starter, Business, Enterprise
Monthly recovery emails, 500, 5000, Unlimited
Custom sender domain, {no}, {yes}, {yes}
Priority live support, {no}, {partial}, {yes}
:::

Write the rows as CSV between :::table and :::: the first row is the header, commas separate cells, and a cell that contains a comma goes in quotes. The older ```csv fence still works.

Do and don't

Do: use CSV format for easy editing and clean diffs. Don’t: cram more than 5 columns into standard text width.

Snippet

Use when: Reusable centralized blocks like newsletter boxes or bios.

:::snippet{name="newsletter"}
:::

A block written once and reused on many pages, like a newsletter sign-up or an author box. Put its name in, and the whole block appears. When the snippet is updated, every page using it updates too.

Need a new one? Ask the admin. Snippets are created centrally so they stay consistent.

Do and don't

Do: use for blocks that need identical copy across multiple pages. Don’t: create a snippet for one-off content used only once.