Why Use Markdown
“There is Word, why do I need Markdown?” is the question almost every beginner asks once. This page is going to give an answer you can act on rather than a slogan, because the honest answer is not that Markdown is more advanced. It is that Markdown moves the cost of a document from the moment of writing to the moment of maintaining it, and for anything that has to be maintained, that is the better trade. The rest of the page makes that concrete: first the five advantages and what each one actually buys you, then a single requirement document written both ways, so you can see the difference at the exact moment it matters, when someone has to review a change to it.
Focus on writing. The syntax is small enough to learn in an afternoon, and it never asks you to think about layout. A heading is a hash, a list is a dash. There is no concept of a text box, a floating frame, or a table cell width, so there is nothing in the source that competes with the sentence you are trying to write.
Cross-platform. The file is plain text, so it opens with any editor on any operating system, and the same file renders on GitHub, in a terminal, in a browser, and inside a slide deck. Nothing about the document is tied to the program that produced it.
Version-control friendly. This is the advantage that is hardest to replicate with anything else, and the next section shows exactly why.
Easy to convert. A Markdown file can be exported to HTML, PDF, slides, or an ebook by a single command, usually with a tool such as Pandoc. The source stays the source, and the published artefact is generated from it.
Extensible. Tables, task lists, syntax highlighting, footnotes, and formulas are all available as extensions on top of the core syntax, and a renderer that does not support one simply ignores it. Each of these is a convenience except one: the first four save effort at the moment of writing, while version control saves effort at the moment of reviewing, which is where documents in a team actually accumulate their cost.
Suppose a team is writing a requirements document for a checkout endpoint. Here is the Markdown version, exactly as it would sit in the repository:
# Checkout API requirements
- The endpoint must return results within 200 ms.
- All monetary values are stored in minor units.A renderer turns that into ordinary HTML, with the list markers expanded into tags:
<h1>Checkout API requirements</h1>
<ul>
<li>The endpoint must return results within 200 ms.</li>
<li>All monetary values are stored in minor units.</li>
</ul>Now the review. A day later the service target is tightened and a caching requirement is added. Because the file is plain text in a Git repository, git diff shows the reviewer precisely which words moved:
diff --git a/requirements.md b/requirements.md
index f09a817..b165ca4 100644
--- a/requirements.md
+++ b/requirements.md
@@ -2,3 +2,4 @@
-- The endpoint must return results within 200 ms.
+- The endpoint must return results within 100 ms.
- All monetary values are stored in minor units.
+- Results are cached for 30 seconds.The reviewer reads one removed line and one added line. They know the old target, they know the new target, and they can tell that caching was added as a separate requirement rather than folded into the latency one. The review takes seconds, and the decision is recorded in the repository history next to the code that implements it.
The same change made in a rich text editor produces something else entirely. A .docx file is a compressed archive, so Git cannot compare it line by line and says so:
diff --git a/requirements.docx b/requirements.docx
index 6d44e0f..c88ad1a 100644
Binary files a/requirements.docx and b/requirements.docx differThat single line is the whole report. The reviewer knows the file changed and nothing else. To find out what changed they have to download both versions, open them in a word processor, and compare them by eye, or convert them to text and hope the conversion preserved the meaning. The cost of that comparison is paid every single time somebody edits the document.
This is the difference in one sentence: Markdown moves the review burden from the reader to the diff. For a document that changes often and is read by more than one person, that is the difference between a ten-second review and a ten-minute one.
The costs of each approach line up with that:
| Approach | Cost of writing | Cost of reviewing a change |
|---|---|---|
| Markdown | A few lines of text, tags supplied by the parser | A line-by-line diff the reviewer can read in place |
| HTML | An opening and closing tag for every element, lists closed item by item | A diff dominated by markup, with the prose buried in it |
| Rich text | Point-and-click, fast for the first draft | A binary blob, so no useful diff at all |
The scenarios that benefit most share the same three properties: the content is mostly words, it needs to survive for a long time, and at some point somebody other than the author has to read it. READMEs, technical documentation, and design notes live next to the code they describe; blogs and knowledge bases are published by a static site generator reading the Markdown source; meeting minutes, standard operating procedures, and requirement documents all end up reviewed by someone else; slide decks are produced from the same source by tools such as remark or reveal.js; and anything written here may later be pasted into a ticket, a chat message, or a pull request comment.
Markdown is a structured plain text format, not a universal document format. The test is simple: if the value of the document is mainly in the words and their hierarchy, Markdown is right; if the value is mainly in the appearance, use a tool built for appearance.
| Requirement | Better choice |
|---|---|
| Precise control of columns, margins, and mixed text-and-image layout | A layout or design tool that exports |
| Real-time collaborative editing with comments and presence | An online collaborative document |
| Rich interaction, forms, and animation | A front-end framework, not a document syntax |
| Long-term archiving where the layout must be frozen | PDF or another fixed-layout export |
Markdown is structured plain text, not a universal document format. The decision rule is short: if a document’s value is mainly in the text and its hierarchy, write it in Markdown; if the value is mainly in the layout, hand it to a layout tool. Choosing wrongly in either direction is expensive, so decide this before you write the first line rather than after.
Below is a project description written as plain text. Rewrite it as Markdown, and then answer the second question: if this file is committed to a Git repository and someone edits one line of it, what will the reviewer actually see?
Project name: kuaiyizhi
Install: npm install
Run: npm startApproach:
The rewrite has one rule: turn the label-style description into a structure-style document. The project name becomes a heading, the two actions become a list, and each command becomes inline code, because a command is a literal string rather than prose. The second half of the question depends on how the file is stored: text on disk is diffed line by line, and a binary document is not.
Steps:
- Rewrite the description, using a heading for the name, a list for the two commands, and inline code for each command, because a command is a literal string rather than prose.
- Commit that file to a Git repository and edit one line, such as changing
npm starttonpm run dev. - Run
git diff. Git compares the two versions line by line, so the output shows the changed line with the old one removed and the new one added, and the untouched lines of the file appear as context. - Contrast this with storing the same content as a
.docx. That file is a compressed archive, so Git reports onlyBinary files ... differand the reviewer has to open both versions and compare them by eye.
Answer:
The rewritten file is:
# kuaiyizhi
- Install: `npm install`
- Run: `npm start`In a Git repository the reviewer sees a line-by-line text diff, so the exact line that changed is visible directly in the review, together with the surrounding lines for context. If the same content were stored as a .docx instead, Git would report only that the binary file differs, and the reviewer would have to download and compare both versions manually.
You should now be able to justify the choice of Markdown in terms a colleague would accept: the writer stays focused on content, the file survives every platform and every tool, the document can be exported to any format, and extensions cover what the core leaves out. Most importantly you should be able to make the argument that decides most cases, which is that a plain text document can be reviewed as a diff, and a document that cannot be reviewed cannot be safely maintained by a team. The next page turns to the practical question that follows from all this: which tool should you actually type into.