Markdown for Beginners: The Only Guide You Need

Markdown has quietly become one of the most important text formats on the internet, powering everything from GitHub README files to Slack messages, Notion pages, and static websites. Despite its ubiquity, many people who use it daily never formally learned it — they picked up a few symbols by trial and error. This guide covers Markdown properly, from the absolute basics to features most tutorials skip.

Why Markdown Exists

Before Markdown, formatting plain text for the web meant writing raw HTML — wrapping every paragraph in <p> tags, every bold word in <strong> tags. This was slow and made the source text hard to read. John Gruber created Markdown in 2004 with one core goal: a Markdown document should be readable as plain text, even without being converted to HTML. A line starting with # just looks like a heading to a human eye, the same way it renders as one after conversion. This readability-first philosophy is why Markdown spread so widely — it's approachable for non-programmers while still being precise enough for automated tools to parse reliably.

Headings

Headings use the # symbol — one for a top-level heading (H1), up to six for the smallest heading (H6). A space must follow the hash symbols: # Main Title creates an H1, ## Section creates an H2. Most documents should have exactly one H1 (the document title) and use H2/H3 for the body's section structure, mirroring how you would outline a document in a word processor.

Text Emphasis

Wrap text in double asterisks or double underscores for bold: **bold text** or __bold text__. Single asterisks or underscores create italic: *italic text* or _italic text_. Combining three asterisks gives bold italic: ***both***. Double tildes create ~~strikethrough~~ text in most Markdown flavours (including GitHub's): ~~struck out~~.

Lists

Unordered lists use a hyphen, asterisk, or plus sign followed by a space: - Item one. Ordered lists use a number followed by a period: 1. First step — interestingly, Markdown renderers automatically number sequentially even if you write "1." for every line, since the actual digit is often ignored in favour of position. Nested lists are created by indenting sub-items with 2 or 4 spaces beneath a parent item, consistent indentation matters for correct nesting.

Links and Images

A link uses square brackets for the display text followed immediately by parentheses containing the URL: [HukhLatri](https://hukhlatri.in). Images use nearly the same syntax with an exclamation mark prefix: ![alt text](image-url.jpg) — the alt text is important both for accessibility (screen readers announce it) and for SEO, since search engines cannot "see" images directly.

Code: Inline and Blocks

Wrap a short code reference in single backticks for inline code: `variable_name`. For multi-line code blocks, use triple backticks on their own line before and after the code, optionally specifying a language right after the opening backticks for syntax highlighting: ```javascript followed by your code, then closing triple backticks. This language hint is what makes GitHub and most modern renderers apply colour-coded syntax highlighting automatically.

Blockquotes

A greater-than symbol at the start of a line creates a blockquote: > This is a quote. Multiple consecutive lines starting with > are merged into a single blockquote block, commonly used for citing sources, highlighting important callouts, or displaying testimonials in rendered documents.

Tables (GitHub Flavored Markdown)

Tables use pipes to separate columns and a special separator row (using hyphens and colons) to define the header boundary and column alignment:

The colons in the separator row control alignment — a colon on the left aligns left, colons on both sides center the column, and a colon only on the right right-aligns it.

Horizontal Rules and Line Breaks

Three or more hyphens, asterisks, or underscores on their own line create a horizontal divider line — useful for visually separating sections. For line breaks within a paragraph (without starting a new paragraph), end a line with two trailing spaces, or use a blank line to start an entirely new paragraph — a single line break without trailing spaces is typically ignored and rendered as a continuous line.

Where You'll Actually Use Markdown

GitHub uses Markdown for README files, issues, pull request descriptions, and comments — it's effectively the required literacy for open-source collaboration. Notion, Obsidian, and most modern note-taking apps use Markdown or Markdown-inspired shortcuts as their default formatting syntax. Static site generators like Jekyll, Hugo, and Astro build entire websites from folders of Markdown files. Even chat platforms like Slack and Discord support Markdown subsets for basic message formatting.

The best way to internalise Markdown syntax is to practice with instant visual feedback. Our Markdown Preview tool renders your Markdown live as you type, side by side with the raw syntax — letting you see exactly how each symbol translates to formatted output without needing to publish anywhere first.