Live
Powered by

Markdown writer

Guidelines for writing well-formed Markdown. Use whenever writing, generating, converting, or editing Markdown content — including converting documents (PDFs, Word files, etc.) to Markdown, drafting Markdown files, or producing Markdown output of any kind.

Guidelines for producing correct, well-formed Markdown.

General

Do not use em dashes (—) ever.

Headings

Use sentence case for all headings — capitalize only the first word and proper nouns. Do not use title case.

Correct:

## Why this matters
## Getting started with Retype

Wrong:

## Why This Matters
## Getting Started With Retype

Line breaks

CommonMark (and most Markdown renderers) treats a single newline as a soft line break — adjacent lines are joined into the same paragraph. To force a visible line break within a block of text, append \ (backslash) to the end of each line that should break.

Correct — address blocks, contact info, multi-line fields:

**Jonathan Wood Design**\
2914 West 3rd Avenue\
Vancouver BC V6K 1M7\
jon@jonathanwood.com\
jonathanwood.com

Wrong — will render as one run-on line:

**Jonathan Wood Design**
2914 West 3rd Avenue
Vancouver BC V6K 1M7
jon@jonathanwood.com
jonathanwood.com

Apply \ line breaks whenever consecutive lines within the same block must render on separate lines:

  • Postal addresses
  • Contact details
  • Multi-line labels or captions
  • Any content converted from a source format (PDF, Word, etc.) where line breaks are meaningful

Blank lines (paragraph breaks) do not require \ — they already produce a visual break.

Tables

Use pipe tables for structured data. Always include a header row and alignment row.

| Column A | Column B |
|---|---|
| value | value |

For invoice-style or key-value data, use a two-column table with no visible header:

| | |
|---|---|
| **Label** | Value |

Tilde escaping in content

Always escape tildes using \~ instead of ~, if using in content such as plain text or within table cells.

Correct:

| Total | \~1771 kcal |
| Carbs | \~247 g |

Wrong:

| Total | ~1771 kcal |
| Carbs | ~247 g |

Exception: inside plain ~~~ fenced code blocks, do not escape the tilde - plain ~ is correct there.

Retype projects

When writing Markdown for a Retype documentation project, also load and apply the retype-docs skill. It covers Retype-specific frontmatter, components, American English conventions, and the docs workflow. The rules in this skill apply alongside it.

Document conversion

When converting documents (PDF, Word, Excel, etc.) to Markdown:

  • Reconstruct multi-column layouts as tables rather than preserving the raw text extraction order.
  • Apply \ line breaks to any address blocks or contact details.
  • Use ## headings for major sections (Summary, Line Items, Payment Options, etc.).
  • Preserve original values exactly — do not round, abbreviate, or infer missing data.

Raw URLs can be included as-is without wrapping in angle brackets, such as <https://www.instagram.com/cts_trainright/> can be simplified to https://www.instagram.com/cts_trainright/.