Nick Hart

Markdown Writing Workflow: How I Write 3x Faster

Nick at his laptop showing his workflow: from idea to markdown code to formatted document.

Written by

Nick Hart

in

The Power of Writing Everything in Markdown First

I’ve been writing tons of resumes, cover letters, and blog posts lately. Word processors felt cumbersome—too much time formatting, too much repetitive work. Then I realized: why not approach writing like an engineering project?” Instead of jumping straight into WordPress, Google Docs, or Apple Pages, I now write everything in VSCode using markdown.

Blog posts, resumes, cover letters, interview notes, writing assignments… they all go into markdown first. Then I use Pandoc to convert them to whatever format I need.

The results? I’m faster, more focused, and my content is way more portable.

Why Markdown Makes Sense 📝

I find writing in a word processor to be distracting—there are so many formatting choices. I just want to focus on the content and have a standard format for the output. This is why markdown appeals to me. It’s simple and consistent.

Perhaps it’s the engineer in me, but I feel like I have more power and control over the structure of my writing. It’s easier to “refactor” the structure of my prose and move ideas around for a better flow.

Markdown gets all the formatting out of the way. You focus purely on content and structure. The syntax is dead simple: **bold**, *italics*, # headers, - lists, and [links](url) — but nothing more.

Why VSCode? ⚡

VSCode helps keep my files organized, easy to find, easy to search, and fast to switch context. It’s a fast, flexible text editor, and extension support for Markdown and other formats is a huge time saver.

All of my files are organized into folders in a single project. When I’m done writing a resume I can quickly switch to my cover_letters folder, create a new markdown file, copy/paste my boilerplate contact info, salutation, and start writing.

Also VSCode has a great built-in preview that lets you see how the markdown will render. The stroke of a few keys (Cmd + shift + V on macOS) and you can see the results instantly.

The Secret Sauce: Pandoc 🔧

I use Pandoc to do my conversion. It’s a simple command line tool that you can run from the terminal inside VSCode. I used to keep Terminal windows open all over the place to run command line tools, but using the terminal integrated into VSCode helps keep everything organized and in one place.

Project Structure 📂

I mentioned using VSCode to keep my files organized. Here’s a rough sketch of my project structure:

writing/
├── blog/
│   └── formatted/
├── assignments/
│   └── company_x/
│   └── company_y/
├── resumes/
│   └── formatted/
├── cover_letters/
│   └── formatted/
└── interviews/
    └── company_x/
    └── company_y/

I keep the markdown organized into top-level folders (blog posts, assignments, resumes, interviews, etc.) and for interviews and assignments I use sub-folders for each company. Any place I want to generate a formatted version from markdown I use a formatted sub-folder.

On occasion if I feel the need to do some custom formatting in a wordprocessor I add some notation to the edited filename (eg: resume_company_x_edited.docx) as a reminder not to blow it away by re-generating from the markdown.

Version Control with Git 📋

Since I’m treating writing like an engineering project, I use Git to track all my markdown files. This gives me powerful revision history, the ability to see exactly what changed between drafts, and easy restoration if I mess something up.

VSCode’s Git integration makes this even better—I can see at a glance which files have changes, view diffs right in the editor, and commit directly from the IDE without switching to the terminal.

I keep a .gitignore file that excludes the generated content:

# macOS
.DS_Store
._*

# Ignore generated formatted files
*/formatted/
*.pdf
*.docx
*.html

# But keep the reference template(s)
!reference.docx

This way my repository stays clean with just the source markdown files, but I can still track my reference templates. The formatted outputs are disposable since I can regenerate them anytime with pandoc.

The Workflow 🚀

Here’s what my typical workflow looks like now:

  1. Open VSCode and create a new .md file in the appropriate folder
  2. Write the entire piece without worrying about final formatting
  3. Preview the markdown in VSCode and make sure it looks good
  4. Convert to whatever format I need (HTML for WordPress, DOCX for resumes, etc.)
  5. Proofread the formatted version (check fonts, margins, spacing, etc.)
  6. Upload the formatted version to WordPress, a job application, or anywhere you need it

I have a bunch of aliases for pandoc that make the conversion process a breeze. Add these to your ~/.bashrc or ~/.zshrc file to make them available in your terminal.

# HTML for blog posts (clean, WordPress-friendly)
md2html() {
    pandoc --no-highlight --wrap=none -t html -o "./formatted/$(basename "$1" .md).html" "$1"
}

# DOCX with reference template
md2docx() {
    pandoc --reference-doc=reference.docx -o "./formatted/$(basename "$1" .md).docx" "$1"
}

# PDF via LaTeX
md2pdf() {
    pandoc -o "./formatted/$(basename "$1" .md).pdf" "$1"
}

Each format serves a specific purpose: HTML works perfectly for pasting into WordPress or web platforms, DOCX is what most job applications expect for resumes and cover letters, and PDF is ideal for sharing finalized documents that need to look identical everywhere. You can use PDF for resumes and cover letters, but I have read that some ATS scanners can choke on it, which is why I stick to DOCX.

Making a Reference DOCX Template ⚙️

To create a reference DOCX template, start by generating a basic one from any markdown file: pandoc sample.md -o reference.docx. Then open this file in Microsoft Word (or your favorite word processor which can export to DOCX) and customize all the styles you care about: fonts, margins, headings, paragraph spacing, etc. The key is to modify the actual Word styles (like “Heading 1”, “Normal”, “Strong”) rather than just formatting individual text, since pandoc maps markdown elements to these named styles. Save the file, and now every time you use --reference-doc=reference.docx, your converted documents will inherit this formatting. You only need to set this up once, and it works great for making professional-looking resumes and cover letters that maintain consistent branding across all your materials.

You can also put this file somewhere central like ~/.pandoc/reference.docx so you can easily access it from anywhere. However, for my workflow I like to keep a separate reference.docx in each project folder so I can easily customize the formatting depending on the type of content.

The Portability Game-Changer 🎯

The portability of using markdown and Pandoc is incredible. I usually generate my resumes into DOCX format because I think ATS scanners sometimes choke on PDF, but if you want it in PDF it’s just a one line command.

The learning curve for Markdown is minimal too (although if you’re an engineer you’re already probably familiar with it). If you can remember that # makes headers and **text** makes things bold, you’re 90% there. GitHub has a great tutorial on using Markdown. It’s very handy if you need a quick reference or refresher.

Future Automation Ideas 🔮

I’m planning to automate this even further. Git hooks could automatically regenerate formatted versions whenever I commit changes. Imagine pushing a blog post update and having the HTML automatically ready for WordPress!

I’m also thinking about a simple script that can create new WordPress posts directly from my markdown files and leveraging WP-CLI.

The best workflows are the ones that get out of your way and let you focus on what matters: the actual work.

Have you tried writing in markdown? I’d love to hear about your workflow experiments.

More posts