Markdown for Beginners: How to Write Headings, Lists, Links, and Tables

Blog posts, technical documentation, GitHub README files, and much more are now written in Markdown. Its appeal is that you can express headings, lists, and links with just a few symbols, without memorizing complex tags like in HTML. This article explains, for first-time learners, what Markdown is, how to write it, and how to use it in practice.

What Is Markdown

Markdown is a lightweight markup language for writing structured documents by adding simple symbols to plain text. Created in 2004 by John Gruber and collaborators, it was designed with readability as the top priority.

Markdown is widely used for three reasons:

• Readable as you write: it uses minimal symbols, so the source text remains easy to understand even before conversion.
• Works anywhere: it is just a text file, so it can be edited in any editor and works well with version control.
• Converts to HTML: what you write can be turned directly into web page HTML for blogs and documentation sites.

For example, writing the following produces a large heading and a bulleted list:

# Title
- Item A
- Item B

Once you learn what the symbols mean, you can write clean documents with nothing more than a text editor. Note that Markdown has several "flavors," and GitHub Flavored Markdown (GFM), which supports tables and checkboxes, is now the de facto standard.

Core Syntax: Headings, Paragraphs, Emphasis

Start with the three building blocks of any document: headings, paragraphs, and emphasis.

Headings

Put # at the start of a line to make a heading. The number of # marks sets the heading level, from one to six. Always put a space after the # marks.

# Top heading (h1)
## Section heading (h2)
### Sub heading (h3)

Paragraphs and line breaks

Separating text with a blank line creates a new paragraph. A simple line break is often not treated as a break; to force one, put two spaces at the end of a line, or use a blank line to split paragraphs.

Emphasis (bold and italic)

Wrap text in * or _ for emphasis. One symbol makes italics, two make bold.

**this becomes bold**
*this becomes italic*
~~strikethrough~~ (GFM)

Use bold for key terms and italics for nuance to keep text readable. The best way to learn is to write and check the result, and with the Markdown Editor you can preview on the right exactly how your syntax on the left will appear.

Lists, Links, and Images

Lists and links are where Markdown really shines.

Bulleted and numbered lists

Put - (or an asterisk) at the start of a line for a bullet, or a number with a period like 1. for a numbered list. Indent a line with spaces to create nested lists.

- Fruit
  - Apple
  - Orange
1. Step one
2. Step two

Links and images

Write a link as [display text](URL). For an image, add ! in front: .

[WAZA TOOLS](https://waza.tools)

Remember it as "the text to show goes in square brackets, the destination or image location goes in parentheses." Keep image alt text short and descriptive, since it helps screen readers and shows when an image cannot load.

Code, Quotes, and Horizontal Rules

In technical writing, syntax for showing code and quotes clearly is invaluable.

Code

Wrap short inline code in ` (backticks). For multi-line code, use a "code block" fenced by three backticks above and below; add a language name after the opening three for syntax highlighting.

Inline `code` is written like this.

Quotes

Put > at the start of a line for a quote block. It is handy for citing sources or making notes stand out.

Horizontal rules

A line of three or more hyphens or asterisks creates a horizontal dividing rule (for example, ---). Use it where the topic changes significantly to improve readability.

How to Write Tables

Tables are a GitHub Flavored Markdown (GFM) feature, built with the pipe character | and hyphens. The first row is the header, the second is a divider, and rows below are data.

| Item | Price |
| --- | --- |
| Apple | $1.00 |
| Orange | $0.80 |

By changing where you place colons in the divider row, you can set column alignment (left, center, right): :--- for left, :---: for center, and ---: for right.

Aligning the pipes by hand is tedious, and tables break more easily as columns and rows grow, so generating them with a dedicated tool is more reliable. As an article gets longer, pairing it with the Markdown Table of Contents Generator, which builds a table of contents from your headings, helps readers grasp the overall structure.

Exporting to HTML and PDF

The real power of Markdown is that you can convert it into other formats after writing. Choose the output to match your purpose.

Converting to HTML and publishing on the web

Converting to HTML is the most basic use of Markdown. Many blog services and static site generators accept Markdown directly and convert it to HTML for publishing automatically. Writing while checking the preview in the Markdown Editor makes it easier to imagine the published result.

Exporting to PDF

When you want to distribute a proposal or manual, a PDF lets you share the same appearance regardless of the recipient's environment. With the Markdown to PDF Converter, you can turn your Markdown directly into a neatly formatted PDF, convenient for printing or sharing as an attachment.

Using it on GitHub and in documentation

GitHub README files, issues, and wikis support Markdown by default. Writing project descriptions, checklists, and code examples in Markdown produces clear, structured documents. More chat tools and note apps adopt Markdown as well, so it is a versatile skill you can reuse in many situations once learned.

Common Pitfalls and Tips

Finally, here are the pitfalls beginners hit most and tips for improving.

1. Don't forget the space after a symbol: a space is required right after # or -. Omit it and you won't get a heading or list.
2. Use blank lines for breaks: leave one blank line to split paragraphs; a simple line break often has no effect.
3. Tables need a GFM environment: tables and checkboxes are flavor (GFM) features, so unsupported environments will show the raw symbols.
4. You can mix in HTML: many Markdown processors let you write HTML tags directly, but standard syntax is enough to start.
5. Make previewing a habit: frequently checking in an editor's preview that your syntax renders as intended speeds up learning.

Markdown has few symbols to learn yet an extremely wide range of uses across blogs, technical docs, and GitHub. Master the basics of headings, lists, links, emphasis, code, and tables, and you will be writing clean documents right away. Start by typing some text into the Markdown Editor and enjoy watching the display change as you add symbols.