Markdown for Beginners: A Plain Guide to the Basics

Markdown is a way to format plain text with a few symbols: # for a heading, ** for bold, - for a list item. You type them in any text editor, and apps that understand Markdown show them as formatted text. The core syntax is small enough to fit in one table, which you’ll find below.

If you paste an AI answer into a plain editor and see stars and pound signs, that’s Markdown that didn’t get rendered.

What is Markdown?

Markdown was created by John Gruber, with help from Aaron Swartz, and published in 2004 on Daring Fireball. The goal was text that reads fine as-is, even before any formatting is applied. A list in Markdown looks like a list. A heading looks like a heading.

Over time, different apps added their own extras, so there are a few flavors. CommonMark is a standard spec for the core syntax, and GitHub Flavored Markdown adds tables and task lists on top. The basics below work almost everywhere.

What are the basic Markdown symbols?

Here is the core syntax. Type the left column, get the right.

You type	You get
# Heading	A top-level heading
## Smaller heading	A second-level heading
**bold**	bold
*italic*	italic
- item	A bullet list item
1. item	A numbered list item
[text](https://example.com)	A link
	An image
`code`	Inline code
> quote	A block quote
--- on its own line	A horizontal line

A few rules trip up beginners:

• Leave a blank line between paragraphs. A single line break often gets joined into the same paragraph.
• Put a space after # and -. #Heading may not render as a heading.
• Indent nested lists by two or four spaces under the parent item.

How do you write a table in Markdown?

Tables use pipes and dashes. The second row of dashes separates the header from the body:

| Platform | Format | Length |
|---|---|---|
| Blog | Article | 1,200 words |
| Newsletter | Email | 400 words |

Tables are part of GitHub Flavored Markdown, and GitHub’s own guide on organizing information with tables covers alignment and edge cases. The columns don’t need to line up in the raw text. It’s fine if they look ragged while you type.

How do you write code blocks and task lists?

For a block of code, wrap it in three backticks on their own lines. You can add a language name after the opening backticks for syntax coloring in apps that support it.

Task lists are another GitHub extension that many note apps support:

- [ ] Draft the outline
- [x] Pick the topic

An x in the brackets marks the item done.

What is frontmatter in a Markdown file?

Frontmatter is a block of settings at the top of a file, between two lines of three dashes. It’s written in YAML, a simple key: value format:

---
title: Pricing decisions
tags: [pricing, clients]
status: draft
---

Apps read it as data about the note. Obsidian calls these properties, and blogs built on Markdown use the same idea for titles and dates. Two tips: keep keys lowercase, and put quotes around a value that contains a colon.

What are wikilinks?

Wikilinks are double square brackets around a note’s title, like [[Pricing decisions]]. They aren’t part of standard Markdown, but note apps such as Obsidian support them as a fast way to link one note to another without typing a full path.

Once notes link to each other, the app can show backlinks (which notes point here) and a graph of how everything connects. That’s where Markdown notes get more useful than a folder of documents. The ideas behind it are covered in backlinks in notes and knowledge graph notes.

Why is Markdown good for notes you use with AI?

There are three practical reasons.

First, chat assistants already use it. ChatGPT and Claude render Markdown in their answers, so a note you ask for in Markdown arrives with its headings and lists intact.

Second, it’s light. The structure costs a few characters (a #, a -), so a Markdown note spends its room in an AI’s context window on content, not markup.

Third, it’s portable. A .md file is plain text. You can open it in any editor, move it between apps, and keep it under version control. Nothing locks it to one tool.

Format	Readable as raw text	Easy for AI to write	Works across apps
Markdown	Yes	Yes	Yes
Word document	No	Through export	Mostly
Notion page	Through export	Through export	Through export
Plain text, no formatting	Yes	Yes	Yes, but no structure

For more on picking a tool around this, see the best note taking app for AI and Notion vs Obsidian for content creators.

Where should a beginner start writing Markdown?

Anywhere that saves plain text. A good path:

1. Open any notes app that supports Markdown, or a plain text editor, and save a file as something.md.
2. Write a heading, a short list and one link.
3. Add a small frontmatter block with a title and a tag.
4. Link to a second note with [[double brackets]] if your app supports it.

That covers most of what you’ll use day to day. If you want a method for what to put in those notes, Zettelkasten for creators is a good next read.

FAQ

Is Markdown hard to learn?

No. The common symbols fit in the table above, and you can write useful notes with just headings, lists and links.

Do I need special software for Markdown?

No. Any text editor can write it. You only need a Markdown-aware app to see it rendered, and many note apps do that as you type.

What’s the difference between Markdown and HTML?

HTML is the markup web pages are built with. Markdown is a shorter way to write common formatting, and it is often converted to HTML for display.

Can I use Markdown in ChatGPT or Claude?

Yes. Both render Markdown in their answers, and you can ask either one to write notes, tables or outlines in Markdown.

Where Valta fits

Valta stores every note as Markdown with frontmatter and [[wikilinks]], so everything above applies directly. You connect any MCP client, like Claude or Cursor, to your vault, and your AI saves notes in that format. When it saves one, Valta returns related notes so it can add links. The web app then shows the graph. You can edit notes yourself in the web editor too. Any vault exports as a zip of Markdown files that opens in Obsidian, on every plan.

The Free plan gives you one vault and 100 notes. Sign up here.