How to Write in Markdown: Beginner’s Guide
Learn how to write in markdown with this beginner’s guide to headings, lists, links, code, and more—start writing faster and cleaner today.
Introduction
Markdown is a lightweight way to format plain text so you can write headings, lists, links, code, and images without fighting a full word processor. People search for how to write in markdown because they want a faster, cleaner way to create well-structured content with simple syntax that works almost anywhere.
If you write blog posts, notes, documentation, or README files, Markdown saves time and keeps your text easy to read even before it’s rendered. You can learn the core syntax quickly, then use it across many writing tasks in Markdown editors, note apps, and publishing platforms.
This guide covers the essentials you need to start confidently: headings, lists, links, code, images, line breaks, escaping characters, and the difference between Markdown and HTML. It also explains how Markdown works, where people use it, which tools make writing easier, and the most common mistakes to avoid. If you want a broader overview first, the complete markdown guide is a useful companion, and the markdown basics page covers the fundamentals in more detail.
Markdown is easy to learn, forgiving for beginners, and practical for everyday writing.
What Is Markdown?
Markdown is a lightweight formatting syntax for plain text formatting, designed so you can write readable content before it is converted into styled output. It is not a programming language; it is a simple way to add structure with symbols like #, *, and []().
John Gruber created Markdown with Aaron Swartz, and it is now built into many writing tools and publishing platforms. A Markdown file often becomes HTML, which browsers and websites can render as headings, lists, links, and code blocks.
You’ll see Markdown in notes, documentation, and README files such as README.md. To learn the basics of markdown syntax, start with headings, lists, and links.
Why Use Markdown?
Markdown is faster than a rich-text editor because you type structure directly instead of clicking buttons for every heading, bold word, or link. That speed matters when you draft notes, README files, or blog posts, especially if you use the same patterns often; see markdown tips for beginners and the markdown formatting guide.
Because Markdown is saved as plain text, your files stay portable and future-friendly: you can open them in editors like Visual Studio Code, Typora, Obsidian, or Notion, and you can also view or edit them on GitHub and GitLab. Plain-text storage works well with version control, so Git diffs show exactly what changed, which makes collaboration and review easier than in Word or Google Docs. Markdown is also easy to convert to HTML, which is why it fits documentation and web publishing so well.
How Markdown Works
Markdown works by using simple symbols to indicate structure. A parser reads the plain text and converts it into HTML or another formatted output. For example, a line that starts with # becomes a heading, text wrapped in ** becomes bold, and a line written as - Item becomes part of an unordered list.
Different platforms use slightly different Markdown flavors. CommonMark defines a consistent core set of rules, while GitHub Flavored Markdown adds features like tables, task lists, and footnotes in some contexts. That is why the same file can look slightly different in GitHub, Stack Overflow, Obsidian, Notion, or a static site generator.
How to Write Headings in Markdown
Use # for headings. The number of hash symbols determines the heading level:
# H1
## H2
### H3
#### H4
Use one H1 per page or document title, then move down in order when you need subheadings. Avoid skipping levels unless your platform or style guide allows it.
How to Make Bold and Italic Text in Markdown
Use double asterisks or double underscores for bold:
**bold text**
__bold text__
Use single asterisks or single underscores for italic text:
*italic text*
_italic text_
You can combine them when needed:
**bold and _italic_ together**
How to Create Lists in Markdown
Markdown supports both ordered lists and unordered lists.
Ordered lists are best for steps or sequences:
1. First step
2. Second step
3. Third step
Unordered lists are best for items without a required order:
- Item one
- Item two
- Item three
You can nest lists by indenting the child items consistently:
1. First step
- Detail A
- Detail B
2. Second step
Task lists are common in GitHub and some other Markdown editors:
- [ ] Draft the post
- [x] Review the draft
How to Add Links in Markdown
Use the standard link format:
[text](https://example.com)
For example:
[Markdown cheat sheet](https://markdownmastery.com/blog/markdown-cheat-sheet)
If you want a reference-style link, some Markdown flavors support this format too:
[Markdown guide][guide]
[guide]: https://markdownmastery.com/blog/markdown-writing-complete-guide
How to Insert Images in Markdown
Use this image syntax:
The alt text should describe the image clearly for accessibility and for readers who cannot load the image. For example:
If your platform supports it, you can also add a title:
How to Format Code in Markdown
Use inline code for short code fragments, commands, or filenames:
Use `git status` to check your changes.
Use fenced code blocks for multi-line code examples:
```html
<h1>Hello</h1>
<p>This is a paragraph.</p>
Fenced code blocks are especially useful when you want syntax highlighting in tools that support it. You can also specify languages such as `html`, `js`, or `python` depending on the platform.
## How to Add Line Breaks in Markdown
A blank line creates a new paragraph.
To force a line break inside a paragraph, many Markdown flavors use two trailing spaces at the end of a line, or a backslash in some editors:
```md
First line
Second line
Because line-break behavior can vary, check the Markdown flavor used by your platform if the output does not match what you expect.
How to Escape Special Characters in Markdown
If you want Markdown symbols to appear as literal text, escape them with a backslash. This is useful for escaping characters such as *, _, #, [, ], (, ), and !.
Examples:
\* not italic\*
\# not a heading
\[link text\]
Escaping characters prevents Markdown from interpreting them as formatting.
Common Markdown Syntax Rules
The most common Markdown syntax rules are simple:
- Use plain text with lightweight symbols instead of complex formatting controls.
- Keep blank lines around major blocks like headings, lists, and code blocks.
- Use consistent indentation for nested lists.
- Match opening and closing punctuation in links, images, and emphasis.
- Use the right syntax for the platform you are writing in.
- Prefer readable structure over clever formatting.
Markdown also supports blockquotes and tables in many tools:
> This is a blockquote.
| Name | Role |
| --- | --- |
| Markdown | Formatting syntax |
Markdown vs HTML
Markdown and HTML solve different problems. Markdown is faster and easier for everyday writing, while HTML gives you precise control when you need unsupported formatting, custom layout, or exact spacing.
You can mix HTML tags into Markdown in many editors, which helps when Markdown alone cannot do the job. For example, some platforms allow <br> for a line break or other HTML tags when you need more control. Use that approach only when necessary so your file stays readable.
What Apps Can You Use to Write Markdown?
You can write Markdown in any plain text editor, but dedicated Markdown editors and code editors make the process easier. Common choices include Typora, Visual Studio Code, Obsidian, and Notion. Many Markdown editors also offer live preview and syntax highlighting, which help you catch mistakes quickly.
Markdown is also widely used in GitHub, GitLab, Stack Overflow, and documentation tools. If you want a file for docs or GitHub, create a README.md; for notes, any .md file works.
Can Markdown Be Used for Blog Posts and Documentation?
Yes. Markdown is a common choice for blog posts, documentation, knowledge bases, and project READMEs. Many static site generators use Markdown as the content source, including Jekyll, Hugo, and MkDocs.
That workflow is popular because writers can focus on content in plain text while the generator handles layout and publishing. It also makes version control and collaboration easier.
Is Markdown Good for Beginners?
Yes. Markdown is one of the easiest formatting systems to learn because the syntax is small, readable, and forgiving. Beginners can start with headings, bold, italic, lists, and links, then add images, code blocks, tables, and task lists later.
The main challenge is not the syntax itself but learning the rules of the platform you are using. A Markdown editor with live preview can make that learning curve much easier.
Common Mistakes When Writing Markdown
The most common mistakes are usually small formatting errors:
- Forgetting blank lines around lists, headings, or code blocks
- Using inconsistent indentation in nested lists
- Missing a closing bracket or parenthesis in links and images
- Forgetting to escape special characters when you want literal text
- Skipping heading levels without a clear reason
- Assuming every platform supports the same Markdown extensions
If a list, link, or heading looks wrong, check the punctuation and spacing first. In most cases, the problem is a missing symbol or an extra space.
Conclusion
If you want to learn how to write in markdown, start with the basics: headings, bold and italic text, lists, links, images, inline code, and fenced code blocks. Then practice line breaks, escaping characters, blockquotes, tables, task lists, and footnotes as needed.
Markdown is simple enough for beginners, but flexible enough for blog posts, documentation, notes, and README files. With a good Markdown editor, a live preview pane, and a cheat sheet nearby, you can write clean content quickly and confidently.
For more help, review the markdown writing tips for beginners, the content formatting guide for markdown, and the markdown cheat sheet.