Markdown has quietly become one of the most universal formats in software development. You write it in GitHub, Notion, Confluence, Slack, Linear, and dozens of other tools. You read it in READMEs, documentation sites, changelogs, and pull request descriptions. And increasingly, AI tools — Claude, Copilot, Cursor, and others — generate it constantly.

Yet most developers treat markdown as an afterthought. They write it in VS Code's editor pane, occasionally toggle the preview, and move on. There's a better way.

Where Developers Write Markdown

Let's start with the breadth of it.

README files are the most obvious. Every project has (or should have) a README.md. It's the homepage of your repository — the first thing someone reads before they decide to use your project, contribute to it, or move on.

Documentation sites — Docs, wikis, and sites generated by tools like Docusaurus, MkDocs, Nextra, and VitePress are almost universally markdown-based. You write .md or .mdx files, the tool handles the HTML.

Pull request descriptions on GitHub and GitLab render markdown. A well-formatted PR with headings, bullet points, screenshots, and a testing checklist is dramatically easier to review than a wall of unformatted text.

Issues and bug reports also render markdown. **Steps to reproduce:** and a numbered list beats a paragraph of text every time.

Changelogs in the form of CHANGELOG.md following the Keep a Changelog format are a standard pattern in open source projects.

Architecture Decision Records (ADRs) — markdown files in a docs/adr/ directory documenting why technical decisions were made. Increasingly common in larger codebases.

Project specs and PRDs — many teams write product requirements in markdown in the repository, keeping them version-controlled alongside the code they describe.

Comments in code reviews — GitHub's review interface renders markdown. Write > quoted text and backtick-formatted code references in your comments.

Slack and Discord — both render subsets of markdown. *bold*, `code`, and ```code blocks``` all work.

Features Most Developers Don't Use

Most developers know headings, bold, italic, lists, and code blocks. Here's the rest.

Tables

| Feature     | OpenMark | VS Code |
|-------------|----------|---------|
| Native macOS| ✓        | —       |
| Mermaid     | ✓        | Extension|
| LaTeX math  | ✓        | Extension|

Tables in markdown are underutilised. They're excellent for comparison tables, API parameter lists, environment variable documentation, and anything else with a structured row/column relationship.

The syntax is a bit fiddly (alignment is controlled with :---: in the separator row), but most editors and AI tools will generate table markdown for you from a text description.

Task Lists

- [x] Set up CI pipeline
- [x] Write unit tests
- [ ] Update documentation
- [ ] Notify stakeholders

GitHub renders these as interactive checkboxes in issues and PRDs. In a markdown editor like OpenMark, you can click to check them off and the source updates automatically.

Footnotes

This claim needs a citation.[^1]

[^1]: Source: The original paper, 2024.

Footnotes are supported in GitHub Flavored Markdown and most documentation tools. Useful for technical writing where you want to reference sources without cluttering the main text.

Strikethrough

~~this was wrong~~ this is correct

Useful in changelogs and living documents where you want to show what changed rather than just delete it.

Mermaid Diagrams

Mermaid diagrams in markdown are one of the most useful features for developer documentation that most developers don't know about.

```mermaid
graph LR
  PR[Pull Request] --> CI[CI Pipeline]
  CI -->|pass| Review[Code Review]
  CI -->|fail| Fix[Fix Failing Tests]
  Review -->|approved| Merge[Merge to Main]
  Review -->|changes requested| Fix
```

GitHub, GitLab, and Notion all render this as an actual diagram. It's version-controlled, diffable, and doesn't require any external tools. For architecture diagrams, deployment flows, state machines, and database schemas, Mermaid is the right tool.

For a full tutorial on Mermaid syntax, see How to Render Mermaid Diagrams in Markdown on Mac.

Math with LaTeX

For scientific and engineering documentation, LaTeX math notation is the standard:

The time complexity is $O(n \log n)$ for the average case.

$$\frac{\partial f}{\partial x} = 2x$$

GitHub renders this. Jupyter notebooks render this. If you're writing technical documentation involving algorithms, signal processing, machine learning, or physics, knowing basic LaTeX notation will save you from using Unicode approximations.

For a practical introduction with common formulas, see Getting Started with LaTeX Math in Markdown.

Writing Better READMEs

A README is a landing page. These are the sections that matter:

Project name and tagline — one line describing what it does.

Installation — the exact commands to get it running, in a code block.

Quick start — the minimal example that shows it working. If you can show a 5-line code example that does something useful, do it.

Configuration/API reference — a table of options or endpoints. Markdown tables are perfect here.

Requirements — what dependencies, platform requirements, or credentials are needed.

Contributing — how to run tests, the PR process, code style expectations.

License — one line with a link.

Keep it scannable. Developers skim READMEs looking for what they need. Short paragraphs, bullet points, and code blocks that show rather than tell.

The AI Angle

Here's something worth noticing: AI tools generate enormous amounts of markdown.

Ask Claude or Copilot to write documentation, and it produces markdown. Ask it to outline a system design, and it writes markdown with headings and lists. Ask it to generate a README template, a technical spec, or an architecture document — markdown, markdown, markdown.

This means the amount of markdown files passing through a developer's machine has exploded in the last two years. You're not just writing markdown for GitHub anymore. You're reading, editing, and reviewing AI-generated markdown constantly.

VS Code's preview pane is fine for markdown you're writing alongside code. But for reviewing and editing AI-generated documentation — reading it, polishing it, fixing the tone — a dedicated markdown editor that shows you the rendered output immediately and lets you toggle to edit mode is a better tool.

Why a Dedicated Editor Beats VS Code for Markdown Writing

VS Code is great for code. For writing markdown, it has some friction:

Split-pane tax. The split editor/preview layout cuts your writing area in half. On a 13-inch laptop, this is genuinely limiting.

Mental mode switching. When you're in VS Code, you're in programming mode. The interface is optimised for code — line numbers, syntax highlighting for code, the status bar, the file tree. Writing prose in this environment is possible but not comfortable.

Preview synchronisation. VS Code's preview pane has to be manually triggered and sometimes lags. It's a preview, not a live view.

Heavy for the task. VS Code is a full IDE. If you're opening a README to read it and maybe make an edit, loading a full IDE for that task is like using Photoshop to view a JPEG.

A dedicated editor gives you full-screen, rendered output as the default view. You see what readers see. You toggle to code view when you need to edit. The context switch between reading and editing is lower.

Making the Most of Markdown in Your Workflow

A few habits that make a difference:

Use Mermaid for any diagram you'd normally make in a separate tool. If you're reaching for draw.io or Miro for an architecture diagram, try Mermaid first. It lives in the repo and renders on GitHub.

Write your PR descriptions in markdown. Format them with headings (## Summary, ## Testing, ## Screenshots). Reviewers will thank you.

Keep a CHANGELOG.md following Keep a Changelog format. Automated release notes are convenient, but a human-written changelog with context and reasoning is more useful.

Use ADRs for significant technical decisions. A simple markdown file in docs/adr/ explaining why you chose one approach over another is invaluable six months later.

Take advantage of GitHub's markdown rendering. .md files anywhere in a repository are rendered on GitHub. docs/architecture.md, docs/api.md, CONTRIBUTING.md — all of these render beautifully on GitHub without any build step.

Markdown is simple enough that you can learn the basics in an hour and use it productively the same day. But the advanced features — tables, task lists, Mermaid diagrams, LaTeX math — are worth knowing. They make the difference between documentation that helps and documentation that just exists.

Download OpenMark → — a native macOS markdown editor for reading, editing, and writing markdown on your Mac. Built with SwiftUI, Liquid Glass design, with Mermaid and LaTeX rendering built in.