Lesson 1
What Is Markdown?
Understand Markdown as plain-text formatting for README files, docs, issues, and changelogs.
Markdown is a plain-text format for writing structured documents without HTML tags. Instead of <h1>Title</h1>, you write:
# Title
Instead of <strong>important</strong>, you write:
**important**
The idea is simple: keep the source readable as text, but let tools render it into headings, lists, links, and code blocks.
Where developers use Markdown
Markdown appears constantly in developer workflows:
README.mdin repositoriesCHANGELOG.mdrelease notes- GitHub issue and pull request bodies
- Docs sites that accept
.mdfiles - RFC notes, runbooks, and internal guides
- CMS or email fields that accept HTML converted from Markdown
Markdown vs HTML vs WYSIWYG editors
| Format | Strength | Typical use |
|---|---|---|
| Markdown | Fast plain-text drafting, diff-friendly | README, issues, docs source |
| HTML | Full layout control, inline styling | CMS, email, web pages |
| WYSIWYG | Visual editing | Notion, Confluence, some CMS tools |
Most teams keep Markdown in Git because it works well with version control, code review, and copy/paste between tools.
Key takeaway
Markdown is a writing format, not a theme or renderer. The same Markdown file can look different on GitHub, in a docs site, or in a preview tool depending on the renderer and CSS.
Try the Markdown Preview / Markdown to HTML tool with a short README sample to see how source text becomes rendered output.