What is a .md file? A visual reader's guide to Markdown

Why is a .md file full of # and ** symbols?

A .md file is full of # and ** symbols because those symbols are Markdown's formatting instructions, and an app like TextEdit shows the instructions instead of following them. Open a .md file in TextEdit and you see something like this:

# Launch plan

We ship **beta** on 1 October.

- Finish search
- Record the demo

Open the same file in a Markdown reader and you see a page: a large heading, a sentence with one bold word, two bullet points.

Nothing about the file changed. The symbols are instructions. # means this line is a heading. ** means make this bold. - means this is a list item. An app that understands Markdown follows the instructions and draws the page. An app that doesn't just shows you the instructions.

That's the whole idea. Everything else in this guide is detail.

the file is the recipe. the page is the cake. TextEdit shows you the recipe.

Where did Markdown come from?

Markdown was created in 2004 by John Gruber, with help from Aaron Swartz (Daring Fireball). The goal was to write for the web without typing HTML tags. It was designed to stay readable as plain text, borrowing habits people already used in plain-text email, like wrapping a word in asterisks for emphasis.

The original description left some cases open to interpretation, so different apps began to handle edge cases differently. In 2014 a group of developers launched CommonMark, a precise specification so the same file would look the same everywhere (CommonMark). GitHub later published GitHub Flavored Markdown, which builds on CommonMark and adds popular extras like tables, task lists and strikethrough (GitHub spec).

Many Markdown apps now follow CommonMark for the basics, and many add some of GitHub's extras. That history explains a lot of small surprises, which we'll get to.

Why do Claude and ChatGPT write in Markdown?

Claude, ChatGPT and Cursor write in Markdown because it is plain text that still carries headings, lists and tables. That is why they answer in Markdown and save files as .md. A few practical reasons make it a natural fit:

• It's plain text. Every app, every operating system and every programming language can read it. Nothing breaks when the file moves between tools.
• It carries structure. Headings, lists and tables survive being copied, pasted, emailed and saved. A rich-text document can lose its formatting in the same journey.
• Chat apps already display it. When you see a formatted answer in a chat window, the app is converting the AI's Markdown into a page. Save that same answer to a file and you get the raw symbols back.
• Another AI can read it back. A .md file is easy for the next tool in your workflow to understand, so you can hand a plan from one AI to another without converting it.

That last point is why you shouldn't convert your AI's files into Word documents or Notes just to read them. The .md is the version your tools share. Keep the file, and change how you look at it. When someone else needs it in Word, paste AI text into Word without the symbols and keep the .md as your working copy.

What does each Markdown symbol mean?

Each Markdown symbol in a .md file tells an app how to format the text around it. These are the pieces you'll meet in almost every AI-generated file, with what they turn into.

Headings

A line starting with # is a heading. More # symbols mean a smaller heading, down to six.

# Q4 plan
## Priorities
### Search
Ship partial-name search first.

When you're reading raw Markdown, the headings are your map. Scan for lines starting with ## to see the sections before reading anything else.

Bold, italic and strikethrough

This is **important**.
This is *a side note*.
This is ~~cancelled~~.

Two asterisks (or two underscores) mean bold. One means italic. Two tildes mean strikethrough, one of GitHub's additions, so some apps show the tildes instead.

Lists

A line starting with -, * or + is a bullet. A line starting with a number and a period is a numbered list.

- Design
  - App icon
  - Welcome screen
- Build
1. Draft
2. Review

Nested lists are where raw Markdown gets hard to read. The only thing that shows the nesting is the indentation, usually two or four spaces, and your eyes have to track it down the page.

Links and images

Read the [layout spec](https://example.com/specs/layout).

![The reading view](images/reader.png)

A link is the visible text in square brackets followed by the address in round brackets. An image is the same with an exclamation mark in front. The text in the square brackets becomes the image description.

Long addresses are one of the worst parts of reading raw Markdown. A sentence with two links in it can stretch across three lines of web addresses, and you lose the sentence. In a reader, you just see the words, underlined.

Code

Text between single backticks is inline code: npm run build. A block of code sits between two lines of three backticks, often with the language name after the first set:

    ```swift
    let greeting = "Hello"
    ```

The backticks tell the reader to use a monospace font and, in most apps, to color the code.

Quotes

A line starting with > is a quote. AI tools also use it for notes and warnings.

> Beta opens to the waitlist first.

A quote whose first line is a label in square brackets is a callout, another GitHub addition:

> [!NOTE]
> Beta opens to the waitlist first.

> [!WARNING]
> Don't share the beta link publicly.

GitHub recognizes five labels: NOTE, TIP, IMPORTANT, WARNING and CAUTION (GitHub docs). Apps that support callouts draw each one as a colored box with a title. Apps that don't show an ordinary quote with [!NOTE] sitting in it as text.

Tables

Tables are made of pipes (|) and dashes. The first row is the header. The second row, full of dashes, separates the header from the body.

| Item | Owner | Due |
|---|---|---|
| Search | Jo | Sep 24 |
| Beta | Maya | Oct 1 |

In raw form, tables are the hardest thing to read, especially when the cells are different lengths and the pipes don't line up. Your eyes can't follow a row across. This is often the moment people give up and paste the file somewhere else.

Task lists

- [x] Pricing page copy
- [x] App icon
- [ ] Press screenshots

[x] is done, [ ] is not. Task lists are a GitHub addition, and AI tools use them constantly for plans and checklists. Some readers also add a small progress bar, like 2 of 3 done, so you can see how far along a plan is without counting.

Math

Formulas sit between dollar signs. One pair keeps the formula inside a sentence. Two pairs put it on its own line.

The margin is $m = (p - c) / p$.

$$
\text{total} = \sum_{i=1}^{n} x_i
$$

The code inside is LaTeX, the language scientists use for equations. An app with math support draws proper fractions and symbols. One without it shows the dollar signs and backslashes as they are. AI tools use this for anything with numbers in it, from loan repayments to statistics homework.

Horizontal rules

A line with three dashes, ---, draws a divider across the page. It's also used at the very top of a file for something else, which brings us to frontmatter.

Which parts are hardest to read raw?

Tables, nested lists, long links and diagrams are the hardest parts of a .md file to read raw. A few paragraphs with a heading and a bold word are fine in any app. This table compares the parts that make visual readers give up with what a Markdown reader shows instead.

Footnotes deserve a warning. They're a later extra, and support is patchy. One Clear Reader, for one, shows [^1] and the note as plain text where they were written. If a footnote matters, ask the AI to put the note in brackets inside the sentence instead.

Frontmatter

Many .md files start with a block between two --- lines:

---
title: Quiet Launch Playbook
author: Maya Chen
tags: [marketing, launch]
---

This is frontmatter, information about the document rather than part of it. Websites and note apps use it for titles, dates and tags. When you read the file raw, it's the first thing you see, and it looks like code. Readers deal with it in different ways: some hide it, and One Clear Reader folds it into a small Document details card at the top that you can open if you need it.

Diagrams

AI tools increasingly write diagrams using a text format called Mermaid. A flowchart looks like this:

graph TD
  A[Draft in Claude] --> B[Read it]
  B --> C{Good?}
  C -->|yes| D[Ship]
  C -->|no| A

A Markdown app with Mermaid support draws the boxes and arrows. Without it, you're left imagining the shape from the arrows in the text. Is that still Markdown? The file is. The diagram sits inside an ordinary Markdown code block, but the code inside it is Mermaid, a separate format, including any colors set with classDef or style. That's why the same file shows a colored flowchart in one app and a block of code in another. See how to read Mermaid diagrams and how to add color to them.

Mermaid can also describe pie charts, timelines and sequence diagrams, and most of these are unreadable as text.

Why does a .md file look right in one app and broken in another?

A .md file can look right in one app and broken in another because, thanks to Markdown's history, apps don't all support the same extras. You might see a perfect table in one app and a row of pipes in another. Here's what usually causes it:

• The app follows only the original rules. Tables, task lists and strikethrough aren't part of the original Markdown. Apps that skip GitHub's additions show them as plain text.
• A blank line is missing. Many apps need an empty line before a list, a table or a heading. AI output is usually fine, but hand edits can remove one.
• The indentation is inconsistent. A list indented with a mix of tabs and spaces can break into the wrong levels.
• The diagram needs Mermaid support. Plenty of good Markdown apps don't draw diagrams at all.

If a file looks broken, try it in a second app before assuming the file is wrong.

How can I read raw Markdown faster?

You can read raw Markdown faster by reading its structure first and skipping the symbols. When you only have raw text, a few habits make it much less tiring:

1. Read the headings first. Scroll through and look only at lines starting with #. That's the document's outline.
2. Treat blank lines as paragraph breaks. Markdown joins lines together until it meets an empty one.
3. Ignore the brackets in links. Read the words in [square brackets] and skip the address in (round brackets).
4. Skip the frontmatter. If the file starts with ---, jump to the second ---.
5. Don't read tables row by row. Find the column you need in the header row, then look down that column only.

These help. They don't make raw Markdown pleasant, and for long documents they don't need to. A reader app does all of this for you.

What can't a Markdown file do?

A Markdown file can't set fonts, page layout, comments or merged table cells. Markdown is deliberately small, and it's worth knowing its limits so you don't go looking for something that isn't there.

• No fonts or colors in the file. A .md file says this is a heading, not this is 28-point blue serif. How it looks is up to the app reading it. That's why the same file can look plain in one app and polished in another, and why reading apps can offer themes.
• No page layout. There are no margins, columns or page breaks. Markdown flows like a web page. If you need a fixed layout, export to PDF.
• No comments or tracked changes. Unlike Word or Google Docs, there's no built-in way to leave a note in the margin or see who changed what. People use Git, or ask the AI to summarize its changes.
• No merged table cells. Tables are simple grids. Complicated tables are often better as a list or a spreadsheet.
• Images are links, not attachments. The image isn't inside the file. The file points to where the image is. Move the .md without its images and the pictures disappear.

None of these are problems for the job Markdown does best: carrying structured writing between people and tools. They just explain why the file on its own can feel unfinished until something displays it.

How do I open a .md file so it looks like a page?

On a Mac, double-clicking a .md file usually opens it in TextEdit or a code editor, which shows the symbols. To see the formatted page, open it in a Markdown reader, and set that reader as the default so double-clicking always works. Our guide on opening a .md file on a Mac walks through each option, free ones first.

In One Clear Reader, you don't need to find the file first. Paste the path your AI gave you, or type part of the file name, and it opens formatted. The free version of One Clear Reader draws these for you:

• tables as grids you can sort by clicking a header
• task lists as ticked boxes, with a 3 of 5 done bar once there are two or more
• callouts like > [!NOTE] as colored boxes
• code in its own box, with a Copy button
• Mermaid diagrams as pictures, and math as proper equations
• frontmatter folded into a Document details card

Footnotes stay as plain text, as noted above.

How do I change a .md file without breaking it?

To change a .md file without breaking it, keep its blank lines, pipes and indentation as they are. You'll often want to change one thing: a date, a name, a sentence. A few rules keep the file working:

• Keep blank lines around lists, tables and headings. Removing one can merge a list into the paragraph above.
• Keep the pipes. In a table, every row needs the same number of | separators. Deleting one shifts every cell after it.
• Match the indentation. When adding a nested bullet, copy the spacing of the line above.
• Close what you open. Every ** needs a partner. An unclosed one can turn the rest of the paragraph bold.
• Edit the .md, not a copy. Pasting into Notes or Word and back can strip symbols or add hidden formatting. Editing the file directly keeps it a clean .md that your AI can read again.

Editing next to a live preview is one safe way: you change the text and immediately see whether the table still looks like a table. Another is to check the change before it's saved. One Clear Reader works this way. You edit the Markdown for free, and before anything is written it shows you exactly which lines were added and removed. How to edit a .md file without breaking it covers the common traps.

Is a .md file safe to open?

A .md file is plain text, so opening it to read is low risk. It can't run programs by itself. Two things are still worth knowing:

• Links can point anywhere. Hover or check the address before clicking a link in a file you didn't write.
• Markdown can contain HTML. Some apps display HTML inside Markdown, including images loaded from the internet. A reader that strips scripts and doesn't load remote images, as One Clear Reader does, shows the text without fetching anything.

What does a whole .md file look like, raw and formatted?

A whole .md file from an AI looks like a dense page of symbols raw, and like an ordinary document once formatted. Individual symbols are easy. What wears you down is a full page of them together, which is what AI tools actually hand you. Here's a short but realistic file.

# Onboarding email plan
**Owner:** Maya · **Status:** draft
## Goal
Get new users to open their *first document* within a day.
## Emails
| Day | Subject | Job |
|---|---|---|
| 0 | Welcome | Install and paste a path |
| 1 | Try search | Find a file by name |
| 3 | Make it yours | Pick a reading profile |
## Before launch
- [x] Draft all three emails
- [ ] Check links in `welcome.md`
- [ ] Send a test to the team

The raw version on top takes real effort to read. You have to find the headings, mentally line up the table and translate the brackets. The version underneath is the same information, and you understand it in a glance. That difference is the whole reason Markdown readers exist.

How does Markdown compare with Word, Google Docs and PDF?

Markdown is the lightest of the common document formats: plain text that any tool can read. This table compares Markdown with the formats you already use.

Markdown's advantage is that it's the one format your AI, your code editor, your notes app and a website can all read and write without converting. Its only real weakness is how it looks raw, and a reader app fixes that without touching the file.

What do Markdown words like render and frontmatter mean?

These are the Markdown words that come up most, in plain English.

Render. To convert the symbols into formatting. "It renders the table" means the app draws it as a grid.

Preview. A formatted view shown next to, or instead of, the raw text.

Syntax. The rules for which symbols mean what. "Table syntax" is the pipes and dashes.

Flavor. A variation of Markdown with its own extras, like GitHub Flavored Markdown.

Fenced code block. A block of code between two lines of three backticks.

Frontmatter. Information about the document, between two --- lines at the very top.

Mermaid. A text format for describing diagrams inside a Markdown file.

Callout. A quote that starts with a label like [!NOTE], drawn as a colored box by apps that support it.

WYSIWYG. "What you see is what you get". An editor where you edit the formatted text directly instead of the symbols.

Plain text. Text with no hidden formatting, which any app can open.

Questions people ask