Getting Started with Markdown: The One-Hour Primer

What you will learn

By the end of this guide, you will be able to write confidently in Markdown. You will know the nine core syntax elements, how to choose a free editor, and how to avoid the mistakes that trip up most beginners. The whole thing should take about an hour if you follow along and try each example as you go.

Prerequisites

You need a computer with a text editor. That is genuinely it.

Markdown files are plain text. You could write them in Notepad, TextEdit, or any editor you already have. I will recommend some better options shortly, but do not let tooling delay you. Open whatever you have and start.

Why Markdown matters

Every document you have ever written in a word processor is locked inside a proprietary format. Try opening a .docx file in a text editor and you will see gibberish. Your words are in there somewhere, buried under XML and formatting metadata.

Markdown is different. It is plain text with a handful of simple symbols that indicate formatting. John Gruber created it in 2004 with a single design goal: the source file should be readable as-is, without any processing. A Markdown file from 2004 is still perfectly readable today. Try saying that about a WordPerfect document from the same era.

That plain-text foundation gives you three practical advantages. Your files are future-proof, because plain text never goes obsolete. They work with version control systems like Git. And they are tiny, measured in kilobytes rather than megabytes.

Markdown is now everywhere. GitHub uses it. Static site generators expect it. Note-taking apps like Obsidian, Joplin, and Logseq store everything as .md files. If you write anything on the internet, you will encounter Markdown sooner or later.

Step 1: Create your first file

Create a new file and save it with a .md extension. Call it practice.md. That extension tells editors to treat it as Markdown, but it is still just a text file.

Type the following:

Hello, this is my first Markdown file.

Save it. You have written valid Markdown. Everything that follows builds on this.

Step 2: Headings

Headings use the # symbol. One # is the largest heading, six ###### is the smallest. You must leave a space between the # and the text.

# Main Title
## Section
### Subsection
#### Sub-subsection

Most documents only need three levels. If you find yourself reaching for #### regularly, your document structure might need rethinking.

Try adding a heading to your practice file now.

Step 3: Emphasis (bold and italic)

Wrap text in single asterisks for italic, double asterisks for bold.

This word is *italic* and this word is **bold**.

You can also use ***both together*** if you need to.

Underscores work too (_italic_ and __bold__), but I recommend sticking with asterisks. They are easier to spot when scanning a document and behave more consistently across different Markdown processors.

Step 4: Paragraphs and line breaks

This catches out nearly every beginner. To create a new paragraph, you need a blank line between blocks of text.

This is paragraph one.

This is paragraph two.

Without that blank line, Markdown treats the text as a single paragraph. This rule applies between all block-level elements: headings, paragraphs, lists, code blocks, and blockquotes.

Step 5: Lists

Unordered lists use a hyphen, asterisk, or plus sign followed by a space. I use hyphens.

- Apples
- Oranges
- Bananas

Ordered lists use numbers followed by a full stop and a space.

1. First step
2. Second step
3. Third step

A useful quirk: the actual numbers do not matter. Markdown will number them sequentially regardless. This means you can write every item as 1. and the output will still be correctly numbered. Handy when you are rearranging steps.

1. First step
1. Second step
1. Third step

For nested lists, indent by two or four spaces (be consistent with whichever you choose).

- Fruit
  - Apples
  - Oranges
- Vegetables
  - Carrots
  - Peas

Step 6: Links and images

Links use square brackets for the display text and parentheses for the URL. The brackets come first.

[Kindred Intelligence](https://kindredintelligence.com)

Images follow the same pattern but with a leading exclamation mark. The text in square brackets becomes the alt text, which is important for accessibility.

![A photograph of a sunset over the North Sea](sunset.jpg)

The most common mistake here is mixing up the brackets and parentheses, or forgetting which comes first. Remember: square brackets hold what the reader sees, round brackets hold where it goes.

Step 7: Blockquotes

Prefix a line with > and a space.

> The best way to predict the future is to invent it.

Blockquotes can span multiple lines:

> This is a longer quote that
> spans two lines in the source.

They are useful for quoting sources, highlighting key points, or setting apart important notes.

Step 8: Code

For inline code (a short snippet within a sentence), wrap it in single backticks.

Use the `print()` function to output text.

For code blocks (multiple lines), use triple backticks. Add the language name after the opening backticks to enable syntax highlighting.

```python
def greet(name):
    return f"Hello, {name}"
```

That language identifier is not just cosmetic. It tells the renderer which syntax highlighting rules to apply. Always include it when you know the language.

Step 9: Horizontal rules

Three or more hyphens, asterisks, or underscores on their own line create a horizontal rule.

---

Use these sparingly. They work well for separating major sections in long documents, but subheadings usually do a better job.

Choosing an editor

You can write Markdown in any text editor, but a dedicated one will show you a live preview and catch syntax errors as you type. Here are my recommendations, weighted towards free and open-source options.

Browser-based (no install needed)

Dillinger is the quickest way to start. Open it in a browser, type on the left, see the rendered output on the right. No account required.

StackEdit is similar but adds support for LaTeX equations and UML diagrams if you need them.

Desktop (open-source)

Mark Text is an open-source, WYSIWYG Markdown editor. You type Markdown and it renders it inline as you write. It is clean, fast, and free.

Ghostwriter is backed by the KDE project. It offers a distraction-free writing environment with a live preview panel. Excellent on Linux.

VS Code with the "Markdown All in One" extension is what I use for technical writing. It gives you preview, table of contents generation, and keyboard shortcuts. If you already use VS Code for anything else, this is the obvious choice.

For note-taking

Obsidian deserves a special mention. It stores all your notes as Markdown files in a folder on your computer. No lock-in, no proprietary database. The files are yours. I use it daily, and this site is built from Obsidian vaults.

Joplin and Logseq are open-source alternatives worth exploring if Obsidian's freemium model does not appeal to you.

Common mistakes and how to avoid them

After teaching Markdown to colleagues over the years, I see the same errors repeatedly. Here are the ones to watch for.

Missing blank lines

This is the number one mistake. Markdown needs blank lines between block elements. Without them, headings merge into paragraphs, lists collapse, and blockquotes behave oddly.

# Wrong
This text will merge with the heading on some renderers.

# Right

This text is properly separated.

No space after the heading hash

#Heading is not a heading. # Heading is. The space is required.

Inconsistent list indentation

Pick two spaces or four spaces for nesting and stick with it throughout the document. Mixing them produces unpredictable results.

Forgetting the language on code blocks

A code block without a language identifier still works, but you lose syntax highlighting. It takes two seconds to add python, javascript, bash, or whatever is appropriate.

Expecting identical rendering everywhere

There is no single Markdown standard. CommonMark provides a solid baseline, and GitHub Flavored Markdown (GFM) adds tables, task lists, and strikethrough. But different tools may render edge cases differently. If something looks wrong in one tool, check whether you are relying on a feature specific to a particular flavour.

Skipping heading levels

Going from ## to #### without a ### in between is technically valid but creates accessibility problems. Screen readers use heading levels to build a document outline. Keep them sequential.

Unescaped special characters

If you need to display a literal asterisk, hash, or bracket, prefix it with a backslash.

This \*text\* will not be italic.

Troubleshooting

My headings are not rendering. Check for a space after the # symbol and a blank line before the heading.

My list items are all on one line. Ensure each item is on its own line and there is a blank line before the first item.

My link shows the brackets and parentheses as text. Make sure there is no space between the closing ] and the opening (. They must be adjacent: [text](url).

My code block is not highlighted. Add the language identifier after the opening triple backticks.

Bold or italic is not working. Check that the asterisks are directly adjacent to the text with no spaces: **bold** works, ** bold ** does not.

Next steps

Now that you have the fundamentals, here is where to go from here.

Practice daily. Write your next set of meeting notes in Markdown. Draft a README for a project. The syntax becomes muscle memory within a week.

Learn GitHub Flavored Markdown. It adds tables and task lists, which are genuinely useful.

| Name  | Role       |
|-------|------------|
| Alice | Developer  |
| Bob   | Designer   |

- [x] Completed task
- [ ] Pending task

Try a static site generator. Tools like Hugo, Jekyll, or Eleventy convert folders of Markdown files into complete websites. This site runs on exactly that principle.

Explore Pandoc. It converts Markdown to PDF, Word, LaTeX, EPUB, and dozens of other formats. If you need to hand someone a formatted document, Pandoc is the bridge between your plain-text workflow and their expectations.

The deeper truth about Markdown is not really about formatting at all. It is about owning your words. Every Markdown file you create is a plain-text file that belongs to you, readable by any tool on any operating system, today and twenty years from now. In a world where most writing is trapped inside apps and platforms that may not exist next decade, that independence is worth more than any feature list.