Markdown Is Enough

The Complexity Creep

There's a trend in documentation tooling toward custom component systems. MDX lets you embed React components in markdown. Some tools have their own templating languages. Others require you to learn a plugin system just to add a simple callout box.

We think plain markdown is enough for 90% of documentation.

What Markdown Already Gives You

Here's what standard markdown supports out of the box:

• Headings and paragraphs
• Code blocks with syntax highlighting
• Tables
• Images and links
• Blockquotes
• Lists — ordered, unordered, and task lists
• Horizontal rules
• Emphasis and strong emphasis

That covers:

Use Case	Markdown Handles It?
Getting started guides	Yes
API documentation	Yes
Tutorials	Yes
FAQs	Yes
Changelogs	Yes
Architecture decision records	Yes

The remaining 10% — interactive examples, embedded API playgrounds, dynamic content — those are features, not documentation.

Read More

• Why We Built GetPagemark — the story behind GetPagemark and why we made it
• Private Repos Are Now Supported — build docs from private GitHub repositories securely

Portability Matters

By sticking with plain markdown, your documentation is portable:

• It renders on GitHub
• It renders in VS Code
• It renders in any markdown editor

You're never locked into a specific tool.

How GetPagemark Handles It

GetPagemark parses standard GitHub-flavored markdown with YAML frontmatter for metadata. That's it.

---
title: My Page
description: An example page
---

# Hello World

Your content here.

No custom syntax to learn. No components to import. Just write markdown.

---

The best documentation is the documentation that gets written. And nothing gets written faster than plain markdown in your editor of choice.