Skip to main content

Koenig Editor and Cards (how to write, format, and publish safely)

Ghost uses the Koenig editor, which is a block-based editor built on cards. A card is a content block: text, image, gallery, embed, callout, button, HTML, etc.

This page explains:

  • how to write and format without breaking layouts
  • what each card is best for
  • email vs web differences (very important)
  • micro-details that prevent publishing mistakes

The mental model: “cards are building blocks”​

Think of a post as a stack of blocks. Each block:

  • has its own behavior and styling
  • may render differently on web vs email
  • can impact performance (especially media)
Fast navigation inside the editor

Use Enter to create a new paragraph.
Use / to open the card menu quickly.
Use Cmd/Ctrl + K (where supported) to insert links faster.

The editor layout (what you’re actually looking at)​

Main canvas (center)​

This is where you write and insert cards.

Toolbar and card menu​

  • The + button inserts cards.
  • Typing / opens the card list at the cursor position.

Settings / Publishing panel (right side)​

This is the “safety panel”:

  • status (draft/published/scheduled)
  • publish time
  • tags / author
  • feature image / excerpt
  • access (public vs members)
  • email sending (if enabled)
  • SEO settings
Most publishing mistakes happen here

People focus on the text and forget the panel: wrong tag, missing excerpt, wrong access level, wrong publish time, wrong newsletter audience.

Core writing cards (the ones you’ll use daily)​

Paragraphs, headings, lists​

Use headings to make content scannable.

Recommended structure

  • Title (H1 is the post title)
  • Use H2 for main sections
  • Use H3 for subsections
  • Avoid jumping from H2 to H4 (structure matters)
Heading hygiene

Use headings like a table of contents.
If a section has only one sentence, it might not need a heading.

Markdown card​

Use when you want fast, clean formatting with predictable output.

Best for:

  • quick formatting
  • checklists
  • code blocks (depending on theme)
Markdown vs rich text

Markdown is strict and predictable. Rich text is flexible but sometimes messy. For documentation-style posts, Markdown keeps things consistent.

Divider / Spacer​

Use dividers to separate major sections. Avoid stacking many dividers; it can feel heavy.

Media cards (high impact on performance)​

Image card​

Use for a single image.

Best practices

  • Use images that are optimized (size + compression)
  • Prefer wide images for hero sections, smaller images for inline examples
  • Always add meaningful captions only when needed
Image weight matters

One 6MB image can slow down the whole page, especially on mobile. Aim for “looks sharp” without being huge.

Micro detail: alt text Alt text is useful for accessibility and sometimes SEO. If the image is decorative, keep alt text minimal or skip it. If the image teaches something (screenshot), describe what matters.

Use when multiple images belong together (steps, examples, comparisons).

Do

  • keep galleries focused (3–8 images)
  • use consistent sizes

Don’t

  • dump 20 images in one gallery (hard to scan, heavy to load)

Video / Audio cards​

Use these only when the content genuinely benefits from media.

Email clients often handle media badly

Email rendering is limited. Video embeds may not behave the same across inboxes. If sending as a newsletter, prefer:

  • a thumbnail image
  • a link to the video on the web

Layout cards (make posts look “designed”)​

Callout card​

Great for:

  • warnings
  • quick summaries
  • “do/don’t”
  • key takeaways

Examples of good callouts

  • “Before you publish…”
  • “Do not change slugs without redirects”
  • “Email formatting rules”
Use callouts as pacing

A few callouts make content easier to scan and feel more “alive”. But too many callouts = noise.

Toggle card​

Use for:

  • FAQs
  • optional details
  • advanced notes that would otherwise clutter the main flow

Perfect for

  • “If you’re sending as newsletter…”
  • “Advanced: when to use HTML card…”
  • “Edge cases…”

Button card​

Use buttons for:

  • internal CTAs (read next page, checklist)
  • external links (support, resources)

Button copy rules

  • Use action verbs: “Open checklist”, “View SEO guide”
  • Avoid vague labels like “Click here”

Bookmark card​

When you paste a URL, Ghost can create a bookmark preview.

Best for:

  • linking external sources in a clean, visual way
  • referencing tools/resources
Email note

Bookmark cards may look different in email. Always preview email output.

Embed and advanced cards (use carefully)​

HTML card​

Use this when:

  • you need custom HTML embeds
  • you’re adding a widget that Ghost doesn’t support as a standard embed
HTML inside content can break layout

Bad HTML can:

  • break spacing
  • overflow containers
  • render poorly on mobile
  • render poorly in email

If you must use HTML:

  • keep it minimal
  • test mobile
  • preview email

Code card (if available in your setup)​

Use for code snippets. If you don’t have a dedicated code card, use Markdown fenced code blocks.

Code snippet rules

  • keep lines short (avoid horizontal scrolling)
  • label languages in fenced blocks when possible
  • never paste secrets or API keys
Never publish secrets

Do not paste:

  • API keys
  • passwords
  • tokens
  • private endpoints Even in “internal” docs. Assume anything can leak.

Feature Image vs images inside the post (they are not the same)​

Feature image (post settings)​

Used for:

  • post list cards
  • homepage/feeds (theme dependent)
  • social sharing previews (often)
  • newsletter header previews (sometimes)

Inline image (image card)​

Used for:

  • content explanation and step-by-step visuals
Best practice

Set a feature image for every post that you want to look good in lists and shares. But don’t use a feature image as a replacement for screenshots inside the content.

Excerpt (why it matters more than people think)​

The excerpt is a short summary that can appear in:

  • post cards on the site
  • previews
  • sometimes email contexts

Excerpt rules

  • 1–2 sentences
  • describe value, not fluff
  • avoid repeating the title
Quick test

If someone only read the excerpt, would they know what the post is about and why it matters?

Use internal links to guide readers to:

  • checklists
  • related docs
  • troubleshooting pages

Rule If you mention a process, link to its checklist.

External links should:

  • open reliably
  • be from trusted sources
  • not be required for understanding (whenever possible)
Link stability

If you rely on an external URL for a key step, consider summarizing the essentials in the wiki too. External links die. Wikis should survive.

Email vs Web (the “two worlds” problem)​

When you publish and send a newsletter, your content is rendered in:

  1. the web post
  2. email clients (Gmail, Outlook, Apple Mail, etc.)

Email clients are limited and inconsistent.

Always preview email before sending

What looks perfect on the web can look broken in email.

Email-safe formatting rules​

  • avoid extremely complex layouts
  • keep paragraphs shorter
  • avoid huge images
  • test any embeds
  • prefer plain links over fancy widgets when in doubt
  • strong intro paragraph (the preview text matters)
  • short sections with headings
  • 1–2 key links max
  • a clear CTA (button or link)

Screenshots (how to make them look professional)​

Screenshots are common in wikis, but they can get messy fast.

Do

  • crop to the relevant area
  • blur/hide personal data (emails, names, IDs)
  • use consistent width (don’t mix tiny and huge)

Don’t

  • screenshot an entire screen when only 10% matters
  • include unrelated tabs or bookmarks
Redaction rule

If a screenshot contains:

  • private member data
  • emails
  • financial info blur it or crop it out.

Common mistakes (and how to avoid them)​

Mistake 1: Publishing without checking access level​

You intended “public”, but it’s members-only (or vice versa).

Fix Always confirm access in the right panel before publishing.

Mistake 2: Sending newsletter to the wrong audience​

This is the “can’t undo” mistake.

Fix Use the Newsletter checklist every single time.

Newsletter sending is irreversible

If you send it to the wrong people, you can’t pull it back. Treat the final send step like you’re launching a rocket.

Mistake 3: Changing the slug after a post is already shared​

Broken links + SEO impact.

Fix Avoid slug changes. If necessary, add a 301 redirect.

“Before you hit Publish” mini checklist​

  • Title is clear and final
  • Feature image set
  • Excerpt written
  • Tags correct (primary tag confirmed)
  • Access level confirmed (public/members)
  • Links tested
  • Headings structured (H2/H3)
  • If sending email:
    • preview email output
    • confirm audience/segment
    • subject line reviewed

Internal notes section (customize for your site)​

Add your site-specific editor rules here

Examples:

  • “We never use HTML cards in newsletters”
  • “We always add an excerpt”
  • “We use 5 core tags only: SEO, Updates, Resources, News, Guides”