A Markdown Workflow for Docs

A repeatable loop for writing, reviewing and publishing docs in markdown without losing track of versions.

Keep the source in one place

Pick one directory as the home of the source markdown and do not scatter copies. Every file has exactly one version, and that version is the one everyone edits. Copies in chat, in downloads and in email threads are how a document set drifts out of sync. If a document needs to travel, export it to a standalone file at the moment it is needed rather than maintaining two live copies.

Edit in small, reviewable steps

Make one change per edit: fix one section, reword one paragraph, add one list. Small edits are easy to review, easy to reverse, and easy to explain. When a change touches several sections, split it, or at least label each section separately so a reviewer can follow the thread. The discipline pays off the first time you need to compare two versions.

Review with a diff, not by memory

Before publishing, compare the current version to the last one you shipped. A line diff shows every addition and removal with the line numbers, so you can see exactly what changed and catch the accidental deletion you would otherwise miss. This is the step that turns "I think I only touched one paragraph" into something you can actually verify.

Publish from the rendered output

Render and export only after the diff is clean. Export a standalone HTML file for anything that leaves your machine, and confirm the export is self-contained before you send it. Because the render happens locally, the published output matches what you reviewed, with no surprise reformatting in transit.

A weekly sweep

Once a week, glance over the whole set: dead links, headings that no longer match the section they introduce, and drafts that have sat unfinished. A five-minute sweep keeps a folder of documents from quietly becoming a folder of contradictions. It is the same habit as a weekly review, applied to text.

Naming and folder structure

A flat folder of files with descriptive names beats a deep tree of folders you have to remember. Name a file for what it contains rather than for when it was written, so the name stays useful after the draft is finished. If a document genuinely has versions, keep the previous one as a separate file rather than overwriting it, or rely on version control instead of file copies. The goal is that anyone — including future you — can find the right file without opening five of them.

When to stop writing and start reviewing

The workflow has a natural stopping point: when the diff is clean, the links are checked, and the export opens correctly offline, the document is done. Resist the urge to keep editing. A document that is good enough to ship and is actually shipped beats a perfect document that is never finished, and the review step is what tells you which one you have.

Handing the document to someone else

A workflow that only works for the author is not a workflow. When someone else picks up the source, they need to know which file is current, what the conventions are, and how to produce the output. A short note at the top of the folder — or a one-line comment in each file — is usually enough. The test is simple: could a colleague make a small edit and export it correctly without asking you a question? If not, the workflow is not finished.

Open the markdown tool — free and private

← All markdown guides