Guide
Markdown basics for notes and README files
Headings, lists, links, and fenced code are enough for most notes. This is the small subset that survives GitHub, docs, and editors.
Updated 2026-08-17
Write in plain text, render later
Markdown is a convention: a few characters in a .md file become headings, emphasis, lists, and links when a renderer turns them into HTML. You can still read the source in any editor. That is why README files, issue comments, and static-site posts still use it.
There is no single law of Markdown. Original Markdown, CommonMark, and GitHub Flavored Markdown (GFM) disagree on edge cases: tables, strikethrough, autolinks, task lists. If you write for GitHub, preview with a GFM-aware renderer. If you write for a strict CommonMark pipeline, avoid GitHub-only extras.
The subset you actually need
Headings: a # prefix, then a space, then the title. One # is the page title; do not skip from # to ### without a reason. Emphasis: *italic* or **bold**. Lists: - or 1. at the start of a line. Links: [label](https://example.com). Inline code: backticks. Code blocks: fenced with three backticks and a language tag.
Blank lines separate paragraphs. A single newline inside a paragraph is often ignored (it becomes a space). If you need a line break, check whether your renderer treats two spaces at end-of-line as a break — many people just use a new paragraph instead.
Preview before you commit
A live preview catches the mistakes that look fine in source: an unclosed fence that swallows the rest of the file, a list that became a paragraph because you missed a blank line, a link whose URL still has angle brackets in it. Paste the README into a previewer, scan headings in order, click a link, and only then commit.
HTML inside Markdown is allowed by some renderers and stripped by others. Do not rely on raw <script> or styles. Sanitizing HTML on a public previewer is a safety feature, not a bug.
Keep README files boring
A useful README states what the project is, how to run it, and where to find more. Fancy badges and screenshot balloons do not replace those three things. Use fenced code for commands so copy-paste works. Use relative links for other files in the repo so they survive forks.
The preview tool on this site is for drafting that boring README without installing a local previewer. It is not a CMS. Copy the Markdown back into your repository when it looks right.
Related tool: Markdown Preview