Markdown Basics

By the Syncfusion DevTutorials team · Last updated October 20, 2026

See the same note as plain text, rich text and Markdown. Learn the three readers of every Markdown file, why Markdown survives copy and paste and code review, why AI tools use it, and when to use JSON instead.

One Note, Two Results

Asha writes the refund rules for the support team. She types them in a word processor. She makes the title big and "30 days" bold. It looks good.

Then she copies the note into a chat app, a code review and an AI assistant.

• In the chat app, the title is just a normal line. The bold is gone.
• In the code review, the file is full of hidden tags nobody can read.
• The AI assistant gets the words, but not which line was the title.

Ravi writes the same rules in Markdown. He pastes them into the same three places. The text still reads well everywhere, and the title is still a title.

This lesson shows you why.

In simple words: Markdown is plain text with a few simple marks. People can read it, apps can turn it into a web page, and AI tools can understand its structure.

Set Up the Course

Tell the course a little about you. It changes the examples, the file paths shown for your AI tool, the editor toolbar, and the files in the capstone kit. You can change these at any time.

If you already write READMEs, take the placement check. Each task you pass marks a Chapter 1 lesson as tested out.

TL;DR

TL;DR stands for "Too Long; Didn't Read".

• Markdown is a simple way to format plain text. Use # for a heading, ** for bold text, and - for a list item.
• A Markdown file is a plain-text file, usually saved with the .md extension. You can open and edit it using any text editor.
• A renderer converts Markdown into formatted content, such as a web page or documentation page.
• People and AI tools can read the original Markdown because its structure remains clear in plain text.
• Markdown is usually easier to write and read than HTML, but it is not the best format for every purpose.
• Use structured formats such as JSON or YAML when a program needs data in a specific structure.

A Real-World Example

Think about a handwritten shopping list.

You write "Groceries" at the top and underline it. Below it, you put a dash before each item. Anyone who picks up the list understands it. They do not need special software. They do not need to know your rules.

Markdown works the same way. The marks are simple, and they look like what they mean. A # at the start of a line looks like a title. A - looks like a list item. Even before any app formats it, the text makes sense.

What You Will Learn

In this lesson, you will learn:

1. What Markdown is, and how it differs from plain text and rich text.
2. The three readers of every Markdown file.
3. Why Markdown survives copy and paste, and why it is easy to review.
4. Why AI tools and agent files use Markdown.
5. When to use JSON or YAML instead.

Cheat Sheet

The six marks you will use most

# A big heading
## A smaller heading

This is a paragraph. **This is bold.** *This is italic.*

- A list item
- Another list item

[A link](https://commonmark.org)

`inline code`

The left side is the Markdown you type. The right side is what a renderer makes from it. Change any line on the left and watch the right side change.

You will learn each mark in detail in the next lessons. For now, notice one thing: you can read the left side without any app.

How to Use the Markdown Boxes

Every lesson in this course has Markdown boxes like the one above. Each box has two sides.

• The left side is a Markdown file. You can type in it.
• The right side shows what the Markdown becomes. It updates as you type.

The right side has three tabs. Each tab is one of the readers you will meet in this lesson.

There are also two buttons, CommonMark and GitHub (GFM). These are two common versions of Markdown. You will learn the difference in a later lesson. For now, leave it on GitHub.

Restore Code puts the original Markdown back.

Three Ways to Write the Same Note

Plain Text

Plain text is just characters. There is no bold, no heading, no list. A .txt file is plain text.

Plain text is easy to share. But it has no structure. Nothing says which line is the title.

The box below holds three lines of plain text, with no Markdown marks at all. Look at the Rendered tab.

Plain text has no structure

Refund rules
Refunds are allowed within 30 days.
The customer must have the receipt.

The three lines ran together into one sentence. The renderer did not know the first line was a title. It did not know each line was a separate point. Open the Outline tab: there are no headings.

Now add # (a hash and a space) in front of Refund rules. The first line becomes a big title, and the Outline tab shows it.

Rich Text

Rich text is text that includes formatting such as headings, bold text, colours, lists, and different font sizes.

In a word processor, you apply this formatting using buttons and menus. The application stores the content and its formatting behind the interface. The exact storage format depends on the application.

A web page commonly uses HTML to describe formatted content. For example:

The same note as HTML

<h1>Refund rules</h1>
<p>Refunds are allowed within <b>30 days</b>.</p>
<ul><li>The customer must have the receipt.</li></ul>

Every bold word and every list item needs an opening tag and a closing tag. That is hard to read, and nobody wants to type it.

Markdown

Markdown is plain text with a few marks. You type the marks yourself. A renderer is an app that reads those marks and shows the formatted result. GitHub, VS Code and most chat apps have one.

The same note in Markdown

# Refund rules

Refunds are allowed within **30 days**.

- The customer must have the receipt.

The Rendered tab looks like the word processor version. Now open the HTML tab. The renderer wrote the same tags as the HTML above: h1, p, strong and ul. You typed four short marks instead.

In simple words: Markdown gives you the structure of rich text with the simplicity of plain text.

# Support sync, 14 October

## Decisions

- Refunds over ₹5,000 now need a manager's approval.
- The refund page gets a **Download CSV** button.

## Actions

1. Asha updates the refund policy page.
2. Ravi tells the support team on Friday.

The Three Readers

Every Markdown file is read three times, by three different readers.

Good Markdown works for all three. Bad Markdown can look fine to one reader and break for another. You will see many examples of this in the course.

Why Markdown Travels Well

It Survives Copy and Paste

Many places only accept plain text: chat boxes, terminal windows, forms and AI prompt boxes. When you paste rich text there, the hidden tags are thrown away. Only the words are left. The title is no longer a title.

Markdown is already plain text. Nothing is hidden, so nothing is lost. Look at the left side of the last box again. That is exactly what someone sees if you paste it into a chat. It still has a title, a bold number and a list item.

It Is Easy to Review

Teams keep files in Git, a tool that records every change. A diff shows what changed between two versions, line by line.

A diff works best on plain text. A word processor file is stored in a hidden format, so a diff cannot show the change in a readable way. A Markdown change shows up as the exact line that changed:

A diff of one Markdown change

 # Refund rules

-Refunds are allowed within **30 days**.
+Refunds are allowed within **14 days**.

 - The customer must have the receipt.

The line with - is the old version. The line with + is the new version. A reviewer sees one changed line and the exact words that changed.

Try it yourself. In the box below, change 30 to 14. Only one line of Markdown changes, and only one line on the page changes.

Change one word

# Refund rules

Refunds are allowed within **30 days**.

- The customer must have the receipt.
- Damaged items need a photo.

Why AI Tools Use Markdown

Fewer Tokens

An AI model reads text in small pieces called tokens. A token is often part of a word. Every model has a limit on how many tokens it can read at once, and more tokens cost more.

HTML spends tokens on tags. Markdown spends them on your words.

Go back to the box called The same note in Markdown and open its Outline tab. It shows 94 characters, about 24 tokens. The HTML version above has 125 characters, about 32 tokens. That is 8 tokens saved on one tiny note.

An agent may read dozens of files before it starts a task. The saving adds up.

Clear Structure

Headings tell a reader what each part is about. An AI agent uses them the same way. It can find the "Refunds" section without reading the whole file.

Open the Outline tab in the box below. This is the order-support project's README. The outline is what an agent sees first.

The outline an agent sees

# Order Support

Answers customer questions about orders.

## Install

Run npm install.

## Refunds

### Refund window

Refunds are allowed within 30 days.

### Damaged items

Ask for a photo first.

One # is the top level. Two # signs are one level down. Three are one more level down. The marks alone give a clear outline: Order Support, then Install and Refunds, then the two refund topics.

Now delete the ## in front of Refunds. Look at the outline again. "Refund window" and "Damaged items" now look like they belong to Install. One missing mark changed what the file means to an agent.

Files That Steer Agents

AI coding tools now read Markdown files to learn about a project. You will write these later in the course.

In simple words: in AI work, a Markdown file is often a set of instructions. Write it with the same care as code.

When Not to Use Markdown

Markdown is for text that people and agents read. It is not a data format.

When a program must read exact values, such as an order number or a status, use JSON or YAML. These formats have strict rules, so a program always finds the field it needs.

Here is one order written two ways:

The order as JSON

{ "orderId": "A-1042", "status": "shipped", "items": 3 }

The order as Markdown

Order **A-1042** is shipped. It has 3 items.

A person reads the Markdown easily. But a program has to guess where the status is. If someone rewrites the sentence as "The order has shipped", the guess breaks. In JSON, status is always in the same place, however the text around it changes.

Where Markdown Is Used

• README files on GitHub and GitLab.
• Documentation sites for products and libraries.
• Chat apps such as Slack, Teams and Discord, for bold, lists and code.
• AI chat apps, which usually answer in Markdown.
• Notes apps such as Obsidian.
• AI agent files such as AGENTS.md and SKILL.md.

Common mistakes

Quick Check

Exercises

What to Remember

• Markdown is plain text with a few simple marks: # for headings, ** for bold, - for lists.
• Every Markdown file has three readers: a person, a renderer and an AI agent. Write for all three.
• Markdown survives copy and paste, and its changes are easy to review line by line.
• Markdown uses fewer tokens than HTML, and its headings give agents a clear outline.
• Use JSON or YAML for data that a program reads. Use Markdown for text that people and agents read.

Further Reading

• CommonMark: the shared standard for Markdown that most apps follow.
• Markdown Guide: Getting Started: a short history of Markdown and how renderers work.
• AGENTS.md: the open format for giving coding agents project instructions.

Next: Headings and Paragraphs, where you write headings, paragraphs and line breaks, and fix a note where every line break disappears.