Keeping Your Resume in Markdown (and Exporting It Anywhere)

A Markdown resume is one plain-text file that you edit anywhere and convert on demand. You write resume.md once, then ask Pandoc for a PDF, a Word file, an HTML page or plain text, depending on what each application wants.

Quick answer

Keep a single resume.md, install Pandoc, and run one command per format. The same source can produce all four outputs:

pandoc resume.md -o resume.pdf
pandoc resume.md -o resume.docx
pandoc resume.md -s -o resume.html
pandoc resume.md -t plain -o resume.txt

If your current resume lives in Word, you can convert an existing Word resume to Markdown first and edit from there.

One limit up front: Markdown describes structure (headings, lists, links), not layout. It suits single-column, text-first resumes well. It does not suit resumes built around columns, icons or precise positioning.

Step-by-step

Structure the source file

Put your name and contact line in a YAML front matter block, then use one H2 per section and bullets for each role.

---
title: Ada Example
---

ada@example.com | Lisbon | github.com/ada-example

## Experience

### Senior Engineer, Example Co. (2021 to present)

- Led a migration of the billing service to a queue-based design.
- Cut weekly deploy time from two hours to twenty minutes.

## Education

### BSc Computer Science, Example University

Keep the structure boring on purpose. Predictable headings convert the same way everywhere.

Export to PDF

The command is pandoc resume.md -o resume.pdf. According to the Pandoc manual, the default route goes through LaTeX, so a LaTeX engine has to be installed. You can pick another engine with --pdf-engine. If you would rather style the page with CSS, send the output through HTML and use an engine such as weasyprint:

pandoc resume.md --pdf-engine=weasyprint --css=resume.css -o resume.pdf

The manual lists weasyprint as the default for HTML, with prince, wkhtmltopdf and pagedjs-cli as alternatives. A small resume.css with a font, margins and heading sizes is usually enough for a clean one-page result.

Export to Word

Some applications still ask for a .docx, and Pandoc handles that too. It takes its fonts, spacing and heading styles from a reference document. Generate the default one, edit its styles in Word or LibreOffice, and pass it back in:

pandoc -o custom-reference.docx --print-default-data-file reference.docx
pandoc resume.md -o resume.docx --reference-doc=custom-reference.docx

The manual's advice is to change only the styles in that file, such as Normal, Body Text, Title and the heading levels, and nothing else. Do this once. Every later export reuses it.

Plain text and HTML

For a form that wants pasted text, use -t plain. Add --wrap=none if you do not want hard line breaks, or --columns to set the width (the default is 72). For a web page, -s writes a complete document, --css links a stylesheet, and --embed-resources packs everything into one self-contained file you can host anywhere.

Keep tailored versions

You'll probably tweak your resume per application. Two approaches work well:

• Override values from the command line with -M, or load them from a file with --metadata-file. A defaults file loaded with -d can bundle the options for each output, and command-line options still take precedence.
• Keep each variant on its own branch, so the differences show up as a diff. If that appeals, here is how to version-control your Markdown files with Git.

Once the commands work, wrap them in a short script or Makefile so a full export is one step. For more on the conversion options, see exporting Markdown to PDF and Word with Pandoc.

Common problems and fixes

The PDF splits a page badly. Page breaks are the weak spot of HTML-based PDF output. The author of the pandoc_resume project, a single resume.md built into HTML, Word, plain text and PDF with a Makefile, reports that the wkhtmltopdf route handles page breaks poorly and can even split a line of text. That project moved to ConTeXt for PDF, and notes the result is close to the HTML look but not identical. Try a different --pdf-engine before you fight the layout by hand.

The Word and PDF versions look different. They're styled in two places: the reference document for Word, the CSS or LaTeX template for PDF. Treat those two files as the only place styling lives, and never fix spacing by editing the exported file.

You want columns, icons or a skills chart. Markdown has no layout model, so this is where it stops. If your field expects a visually designed resume, design it in a layout tool and keep the Markdown file as your master record of the content.

Doing this with Carets

Carets is a native notes and code editor for iPhone, iPad and Mac, and a resume.md is exactly the kind of file it handles well. It edits Markdown and plain text directly, with syntax highlighting that makes the YAML block and headings easy to scan. Files, projects and tags let you keep your master resume and its per-application variants together in one project. Because everything stays plain text, the files remain portable, and you can run the Pandoc commands above on your Mac whenever you need a fresh export.

So a quick fix to a bullet point on your phone before an interview takes seconds. No template to open.

Download Carets from the App Store for iPhone, iPad and Mac.

Frequently Asked Questions

Can I keep a resume in Markdown and still send a Word file?

Yes. Pandoc writes .docx from the same resume.md, and --reference-doc lets you set fonts, spacing and heading styles once in a template.

Do I need LaTeX to make a PDF from Markdown?

Pandoc's default PDF route uses a LaTeX engine, but --pdf-engine lets you choose others, including HTML-based engines such as weasyprint that you style with --css.

How do I keep different versions of my resume for different jobs?

Keep one resume.md and put variant settings in YAML metadata or separate defaults files, or keep each variant on its own Git branch.

Is Markdown a good fit for a design-heavy resume?

Not really. Markdown has no layout model, so columns, icons and precise positioning are better done in a design tool.