Markdown for everything: why I write all my docs in it

I write everything in Markdown. Blog posts, project documentation, meeting notes, personal journal entries, README files. It is the most universally useful format I know, and it has replaced Word documents, Google Docs, and Notion pages in my workflow.

Why Markdown works

It is plain text. A Markdown file is a text file. You can open it with any text editor on any operating system. It will be readable in 20 years without any special software. Try saying that about a .docx file or a Notion export.

It is human-readable without rendering. Even without a Markdown renderer, the raw text is easy to read. Headings are prefixed with #, bold is wrapped in **, lists use -. The syntax enhances readability rather than obscuring it.

It is version-controllable. Markdown files work perfectly with Git. You can diff changes, review history, merge edits, and collaborate on documentation the same way you collaborate on code.

It renders everywhere. GitHub, GitLab, VS Code, Obsidian, static site generators, documentation tools. Markdown is a first-class citizen across the entire developer ecosystem.

What I write in Markdown

Project documentation. Every project gets a README.md, a CONTRIBUTING.md if needed, and architecture decision records in an docs/ directory. These live in the repo alongside the code.

Blog posts. This entire blog is MDX (Markdown with JSX). The posts are Markdown files with YAML frontmatter. Writing a new post means creating a new .mdx file.

Personal notes. My note-taking app (Joplin) stores everything as Markdown files. Notes sync across devices and I can read them with any text editor if Joplin ever goes away.

Technical guides. When I set up something new in my homelab, I write the steps in a Markdown file and save it in my notes. Six months later when I need to do it again, the guide is there.

The syntax I use daily

# Heading 1
## Heading 2
### Heading 3
 
**bold text**
*italic text*
`inline code`
 
- Unordered list item
- Another item
  - Nested item
 
1. Ordered list
2. Second item
 
[Link text](https://example.com)
 
![Image alt text](image.jpg)
 
> Blockquote
 
| Column 1 | Column 2 |
|-----------|----------|
| Data      | Data     |

That covers about 95% of my usage. The syntax is minimal enough that I type it without thinking.

Code blocks

Markdown's fenced code blocks with language annotations are essential for technical writing:

```typescript
function hello(name: string): string {
  return `Hello, ${name}`;
}
```

Most renderers add syntax highlighting automatically. This is why Markdown has become the default format for technical documentation.

Tools I use

Joplin for personal notes and documentation.

VSCodium for editing Markdown files in projects. The built-in preview is good enough.

mdx for this blog, parsed by next-mdx-remote at build time.

When Markdown is not enough

For complex layouts (multi-column documents, precise formatting), Markdown is limited. If you need a polished PDF, write in Markdown and convert with Pandoc or use a proper typesetting tool.

For real-time collaboration with non-technical people, Google Docs or Notion is still the better choice. Not everyone knows Markdown syntax.

For everything else, Markdown is the right default.

Sources

• Markdown Guide
• CommonMark Spec