The Markdown resume format, explained

Start with a tiny front matter block

The first lines of the document can describe who you are. Use a simple key: value block between two --- lines — no YAML nesting, no plugins, nothing to break.

          ---
name: Ava Chen
title: Senior Product Engineer
email: ava.chen@example.com
phone: +1 415 555 0132
location: San Francisco, CA
website: avachen.dev
github: github.com/avachen
linkedin: linkedin.com/in/avachen
avatar:
---
        

Only nine fields are read: name, title, email, phone, location, website, github, linkedin and avatar. Every field is optional. If you prefer, skip the block and start with # Your Name — the first H1 becomes the name.

Keep contact details boring Use the email address you actually check, a phone number with a country code, and one portfolio link. Recruiters copy these values; extra punctuation is a tax on everyone.

Use H2 for sections and H3 for entries

Two heading levels carry the whole structure. ## starts a section such as Experience or Skills. ### starts a single role, project or degree. Inside an entry line, use · to separate the title from the organization and | to separate the date.

          ## Experience

### Senior Product Engineer · Lumen Labs | 2021 — Present
- Led the rebuild of an analytics dashboard used by 40k+ teams.
- Shipped a design-system migration across 120 screens.

### Frontend Engineer · Northwind Studio | 2017 — 2021
- Built the checkout flow for a marketplace processing $80M/year.
        

That is the entire markup language. Everything below an H3 is rendered as that entry’s body, so a paragraph followed by bullets stays visually grouped on the page.

Write bullets that survive a six-second skim

A hiring manager rarely reads a resume front to back. They scan the left edge of each bullet, looking for verbs and numbers. Give them both, early.

• Start with an action verb: led, shipped, rebuilt, reduced, negotiated.
• Put the outcome before the tool: “cut checkout latency 38% with a smaller bundle” beats a list of frameworks.
• Quantify one thing per bullet — users, revenue, time saved, team size or percentage.
• Keep bullets under about 180 characters so they stay on two lines at most.
• Use bold sparingly for the few keywords a recruiter should not miss.

Three strong bullets for a role beat six vague ones. If a line cannot be defended in an interview, delete it.

One page, two pages, or somewhere between

One page is the default for under ten years of experience; two pages are fine when every line carries evidence. What matters is that the page count comes from content, not from squeezing the layout.

• Aim for 350–550 English words for a one-page resume, or roughly 900–1300 CJK characters.
• Use the Compact density when you are a few lines over; switch to Cozy when the page feels thin.
• Delete the oldest role’s least relevant bullets before shrinking the font.
• Let the A4 preview show page breaks honestly — a resume that ends mid-bullet in print is a bug.

Five formatting mistakes to avoid

• Mixing heading levels: an H3 outside a section loses its visual anchor.
• Using tables for layout — applicant tracking systems read them unevenly.
• Wrapping dates in emoji or parentheses; keep the | 2021 — Present suffix predictable.
• Embedding your name as an image, which makes it invisible to both search and parsing.
• Pasting raw HTML. Only <br> is allowed, and everything else is stripped for safety.

The format is the point A Markdown resume stays diffable, versionable and portable. If you ever want to leave this tool, your content is still plain text — not trapped in a proprietary document.