DEV Community

Cover image for Markdown Syntax for Beginners: A Practical Guide
Adeel
Adeel

Posted on Originally published at freetoolsnexus.com

Markdown Syntax for Beginners: A Practical Guide

#markdown #beginners #tutorial #webdev

Markdown is a lightweight way to add structure and emphasis to plain text using characters such as #, * and backticks. Learn a few core patterns, then preview your document in the place you plan to publish it.

What Markdown is and why it is useful

Markdown is a lightweight syntax for structuring plain text. A few familiar characters create headings, emphasis, lists, links and code, while the source remains readable even before it is rendered. Markdown files commonly use the .md extension.

It is useful for README files, technical documentation, notes and other writing that benefits from being easy to edit, compare and keep in version control. A renderer converts the syntax into HTML or another format. The original Markdown description left some behavior open, so CommonMark provides a more consistent core specification. GitHub Flavored Markdown (GFM) adds features such as tables, task lists and strikethrough. Because support varies, preview a document in its destination.

The core Markdown syntax

Headings

Start a heading with one to six # characters. More characters indicate a lower-level heading. Add a space after the hashes, use one main heading for the document title, and keep heading levels in order.

# Project notes
## Setup
### Requirements
Enter fullscreen mode Exit fullscreen mode

A consistent hierarchy makes long documents easier to scan and helps assistive technology and search systems interpret the page structure when it is published as HTML.

Paragraphs and line breaks

A blank line separates paragraphs. A single newline inside a paragraph is usually rendered as a space. To force a line break without starting a new paragraph, end the line with two spaces or a backslash:

First line\
Second line
Enter fullscreen mode Exit fullscreen mode

Bold, italic and strikethrough

Use one * or _ for italic text and two for bold. Three markers can combine both styles. Strikethrough with two tildes is a GFM extension.

*italic* and **bold**
***bold and italic***
~~removed text~~
Enter fullscreen mode Exit fullscreen mode

Lists

Use -, * or + for unordered lists. For ordered lists, put a number and period before each item. Indent nested items consistently. GFM also supports task lists:

- Review the draft
- Check the examples
  - Confirm the code block

1. Open the editor
2. Write the content
3. Preview the result

- [x] Write the draft
- [ ] Proofread
Enter fullscreen mode Exit fullscreen mode

Renderers generally count ordered-list items from the first number, so the source numbers do not always need to be sequential.

Links and images

Put link text in square brackets and its destination in parentheses. An image uses the same pattern with an exclamation mark before the brackets:

[Markdown Editor](https://freetoolsnexus.com/tools/markdown-editor)
![A description of the image](https://example.com/images/diagram.png)
Enter fullscreen mode Exit fullscreen mode

Choose link text that explains where the link leads. Give images meaningful alt text so people using screen readers can understand their purpose, and so the description can appear if an image does not load.

Blockquotes and code

Start a quoted line with >. Wrap a short code term in backticks. For longer examples, use three backticks on separate lines; adding a language name can enable syntax highlighting where the renderer supports it.

> Keep examples easy to read.

Run `npm install` to install dependencies.

```json
{"name": "Maya", "active": true}
```
Enter fullscreen mode Exit fullscreen mode

When documenting JSON, check that the example is valid with the JSON Formatter & Validator. To display triple backticks inside another fenced block, use a longer fence around the outer example.

Tables and horizontal rules

Tables use pipes to separate columns and a divider row under the header. Colons in the divider row set alignment. Tables are supported by GFM, but are not part of core CommonMark, so preview them on the platform where the document will appear.

| Format | Purpose |
|:-------|:--------|
| JSON   | Data    |
| YAML   | Config  |
Enter fullscreen mode Exit fullscreen mode

For a horizontal rule, put ---, *** or ___ on a line by itself, with a blank line above it.

Escaping special characters

If a character would normally trigger formatting, put a backslash before it to show the character literally:

\*this is not italic\*
Enter fullscreen mode Exit fullscreen mode

Markdown quick reference

Element Syntax
Heading # Heading
Bold **bold**
Italic *italic*
Strikethrough (GFM) ~~text~~
Inline code `code`
Link [text](https://example.com)
Image ![alt text](image.png)
Blockquote > quote
Bullet list - item
Numbered list 1. item
Task list (GFM) - [ ] task
Horizontal rule ---
Code block Three backticks around the code, optionally followed by a language

Writing Markdown for developer projects

README files and documentation

Markdown keeps project documentation in plain text, which makes it easy to read, edit and review alongside code. Draft in the Markdown Editor with Live Preview to see how headings, lists and code blocks render before committing the file.

YAML front matter

Some static site generators read page metadata from YAML placed between --- markers at the top of a Markdown file. This section is called front matter:

---
title: "Project notes"
date: 2026-10-09
tags: [markdown, guide]
---
Enter fullscreen mode Exit fullscreen mode

If your metadata is in JSON, convert it with the JSON to YAML Converter. For a broader comparison of the formats and their trade-offs, see JSON vs XML vs YAML.

Comparing edits and cleaning up repeated text

Markdown is plain text, so you can compare document versions to review exactly what changed. The Text Diff Checker can help compare two drafts before publication.

For repetitive edits, a regular expression can transform matching text. For example, this pattern and replacement turn a bare URL on a line into a Markdown link:

Find:    ^(https?://\S+)$
Replace: [$1]($1)
Enter fullscreen mode Exit fullscreen mode

Test bulk replacements on a copy first. A pattern that matches more than intended can alter text outside the target lines.

Converting and reusing Markdown

Use the Markdown to PDF & HTML Converter to prepare a document for sharing as HTML or PDF. The PDF to Markdown Converter can turn a PDF into editable text, but review the result: page layout, tables and multiple columns may not map neatly back to Markdown.

Common Markdown mistakes

  1. Leaving out the space after #. Write # Title, not #Title.
  2. Skipping blank lines. Add a blank line before a list or table so it is not interpreted as part of the preceding paragraph.
  3. Inconsistent list indentation. Use a consistent number of spaces for nested items.
  4. Expecting every newline to create a line break. Use a hard-break marker or a blank line when that is the intended layout.
  5. Leaving special characters unescaped. An asterisk or underscore in ordinary text can be interpreted as formatting; escape it or wrap the text in code.
  6. Forgetting to close a code fence. An unclosed fence can make the rest of the document render as code.
  7. Using a pipe inside a table cell without escaping it. Write \| when a literal pipe belongs in a cell.
  8. Assuming extensions work everywhere. Tables, task lists and other additions vary by renderer. Preview the final document in its destination.
  9. Relying on raw HTML. Some platforms limit or remove HTML inside Markdown.

Try the tools in this guide

Top comments (0)