Markdown Explained: Writing That Becomes Any Format

#markdown #tools #beginners #programming

Introduction

Every README on GitHub, every post on Dev.to and Hashnode (the platforms this blog distributes to), and most technical documentation is written in Markdown: plain text with a few simple marks for formatting. It was designed to be readable as-is — even before conversion — and to convert cleanly into HTML, PDF, slides, and more. If you write anything technical, Markdown is the format to learn first.

The syntax in one minute

Markdown's core is small enough to learn in a sitting:

# Heading 1
## Heading 2
**bold text** and *italic text*
- A bullet list item
- Another item
1. A numbered item
2. Another numbered item
[link text](https://example.com)
`inline code` and a fenced code block (shown in the draft file as a nested example)
```
a fenced code block
```

Headings, emphasis, lists, links, and code cover the vast majority of documents. Tables, images, and blockquotes extend it slightly, and "flavours" (GitHub Flavoured Markdown being the standard) add conveniences like task lists (a dash, brackets and a space, then "todo") and strikethrough — all still plain text, all still readable without a tool.

Why plain text wins for documentation

Markdown's power is what it is not: it is not a binary format (like a Word document) that only one program can open, and it is not a layout tool that breaks when a version changes. Plain text works in Git (the Git post) — diffs show exactly what changed, line by line — it works in every editor (including VS Code, from this batch's first post), and it converts to anything later. That is why documentation, notes, and blog posts converge on it: the content outlives the tool that created it.

The honest trade

Markdown is deliberately limited: precise page layout, complex tables, and footnotes vary by flavour or don't exist, and two renderers can display the same file slightly differently. For a polished book or a designed page, you need something richer. But for the documents developers actually write — READMEs, guides, notes, posts — its limits are a feature: fewer choices means faster writing and consistent results.

Takeaway

Markdown is plain text with minimal formatting marks, it converts to HTML and more, and it plays perfectly with Git and every editor. Learn its small syntax once, and you can write documentation, READMEs, and posts for the rest of your career.

Originally published at https://practicaldevblog.blogspot.com/2026/10/markdown-explained-writing-that-becomes.html

DEV Community