Markdown for writers: a practical guide to plain text

Markdown lets you mark the structure of a draft with ordinary punctuation: headings, emphasis, links, lists, and quotations. John Gruber's Markdown: Syntax describes a format designed to remain readable as plain text while supporting conversion to HTML. For a first draft, start with paragraphs separated by blank lines and add formatting only where it expresses a useful distinction. Gruber's syntax guide.

For writers, the practical reason to try Markdown is to keep a readable copy of the work outside a particular editor. Save a local file, learn the small set of marks below, and check a preview before sharing it. The preservation argument follows from Gruber's plain text design: your sentences and basic structural cues remain in the file, available to read and edit when you change tools. Gruber's Markdown project description.

Where Markdown came from

John Gruber created Markdown in 2004. In "Introducing Markdown," dated March 15, 2004, he announced his text-to-HTML tool for web writers. On the project's acknowledgements page, he credits Aaron Swartz with ideas, feedback, and testing that helped shape the formatting syntax. Gruber's announcement and his acknowledgement of Swartz's contribution.

Gruber distinguishes the writing format from its rendered output: the source should be comfortable to read before it becomes a formatted page. His syntax guide also identifies plain text email as a major influence on the notation. Markdown: Syntax, philosophy section.

Try approaching your first Markdown document in that spirit. Write a passage you would be happy to read in an email, then mark its section title and any quotation. Leave decisions about type size and page decoration until you are ready to prepare the piece for its destination.

Portability and freedom from editor lock-in

Gruber's project description defines Markdown as plain text syntax with a conversion tool. From that design, a modest portability claim follows: a saved Markdown draft does not require the original writing app just to expose its words. This is a reason to keep a local source copy, rather than relying solely on access to one service. Gruber's project description.

Test portability on a small draft before changing your routine. Save it, open that saved file in a second text editor, and check the text and punctuation. Then open it in your intended Markdown preview. Inspect headings, emphasis, and links so you know which parts of your working document survive the move.

Define what you need to keep besides the prose. If you depend on comments, attached images, or editorial approvals, include them in your transfer check instead of assuming the text file contains them. Put associated files in a named folder and keep a note of their relationship to the draft.

Treat freedom from lock-in as a practice you can verify. Keep a copy you can open, choose notation your destination understands, and retain the supporting material you need. Do not make the file format carry a preservation promise that you have not tested with your own work.

The Markdown syntax writers actually use

The examples in this table follow the CommonMark project's Markdown Reference. The sample words are original examples for this guide. Enter the punctuation shown in the middle column, including the space after a heading or list marker. CommonMark's reference.

Purpose	What to type	Result in a Markdown preview
Emphasis	*a quiet room*	Italic emphasis
Strong emphasis	**Keep this detail**	Bold emphasis
Main heading	# The evening shift	A first-level heading
Section heading	## A change of plan	A second-level heading
Link	[Markdown guide](https://commonmark.org/help/)	Linked descriptive text
Unordered list	- Read the draft	A bullet item; add each item on its own line
Ordered list	1. Open the notebook	A numbered item; add each step on its own line
Quotation	> The rain kept us indoors.	A block quotation

Choose formatting by function. Use a heading to name a section, emphasis to distinguish a word or phrase, and a list for items you want the reader to consider separately. Reserve numbered lists for a sequence you intend the reader to follow.

For quotations, keep attribution beside the quoted passage. The quotation marker supplies formatting; you must supply the speaker or publication, check the wording, and include whatever context the quotation needs. The rain sentence in the table is invented, so do not present it as something a named author wrote.

Build a small draft before adding features

Try writing a short note about a place you know. Give it a heading, describe one thing you noticed, and add a list of details you want to return to. Use a link only if you have a source or destination that helps the reader.

In Gruber's syntax guide, a blank line separates paragraphs, while a single newline within a paragraph does not normally force a rendered line break. For ordinary prose, use blank lines between paragraphs and check the preview when spacing matters. Gruber's paragraph guidance.

For your first transfer between editors, stick to the reference table. If you want additional features, try each one in a disposable sample and inspect the destination before depending on it in a manuscript. Record the notation that works for your chosen setup in a short reference note.

Keep a history you can inspect

Scott Chacon and Ben Straub's Pro Git, in "About Version Control," describes systems that record file changes over time, let you compare versions, and restore an earlier state. A Markdown draft can be one of those files; version control is a separate tool you choose to use with it. Pro Git, second edition.

If you use version control, save a revision with a short note about the editorial decision: moved the example before the argument, shortened the introduction, or restored a qualification. When comparing versions, assess whether the change served the piece's purpose, rather than counting deletions as progress.

If you prefer a manual routine, make a dated copy before a substantial revision and store it with the project. Keep the names consistent enough that you can distinguish the working draft from an earlier version. Practice recovering one paragraph so your revision habit includes a way back.

Start with one portable piece

Keep the setup small enough to leave attention for the writing. AIWriter's Presence craft reference puts the person's thinking first; apply the same priority when choosing a format. Decide what you want to say, use the marks that express its structure, and inspect the result yourself.

For your next writing session, save one short draft as a Markdown file, open it in a second editor, and confirm that you can still read and revise the whole piece.