# What is a .md file? A visual reader's guide to Markdown > What Markdown is, what every symbol in a .md file means, why AI tools write in it, and how to read and edit it without getting lost. Source: https://oneclearreader.com/guides/what-is-a-md-file · Updated 28 September 2026 · One Clear Reader (Northlight Group Pty Ltd) > [!answer] A .md file is a plain text document written in **Markdown**, a simple way of marking up text with symbols: `#` starts a heading, `**` makes text bold, `-` starts a bullet, and rows of `|` make a table. It only looks like a finished document when an app turns those symbols into formatting, so open it in a Markdown reader instead of TextEdit. ## 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: ```md # 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. > [!scribble] 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](https://daringfireball.net/projects/markdown/)). 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](https://commonmark.org/)). GitHub later published **GitHub Flavored Markdown**, which builds on CommonMark and adds popular extras like tables, task lists and strikethrough ([GitHub spec](https://github.github.com/gfm/)). 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](/guides/paste-ai-text-into-word) 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. ```pair caption: One # is the title. Two is a section. Three is a subsection. # 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 ```pair caption: Emphasis marks wrap the words they change. 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. ```pair caption: Indent a line to nest it under the one above. - 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 ```md 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: ```md ```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. ```pair caption: The angle bracket becomes a quote bar. > Beta opens to the waitlist first. ``` A quote whose first line is a label in square brackets is a **callout**, another GitHub addition: ```md > [!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](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)). 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. ```pair caption: Pipes and dashes in, a real table out. | 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 ```pair caption: Square brackets become checkboxes. - [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. ```md 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. | Culprit | Why it's hard raw | What a reader shows | |---|---|---| | Tables | Pipes rarely line up, so rows blur together | A grid with aligned columns | | Nested lists | Only indentation shows the structure | Clear levels with bullets and spacing | | Long links | Web addresses break up sentences | The words, underlined | | Code blocks | Backticks and language names add noise | A tinted, monospace box, often colored | | Frontmatter | A block of `key: value` lines before the content starts | Hidden, or shown as a title card | | Diagrams | A flowchart written as text, like `A --> B` | The actual diagram | | Math | Dollar signs and backslashes around every formula | A drawn equation, in apps with math support | | Footnotes | Markers like `[^1]` with the note far below | In apps that support them, a small number linked to the note. Many readers leave `[^1]` as text | 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: ```md --- 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: ```mermaid-pair caption: The same flowchart, as text and as a drawing. 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](/guides/read-mermaid-diagrams) and [how to add color to them](/guides/color-mermaid-diagrams). 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](/guides/open-md-file-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](/guides/edit-md-without-breaking) 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. ```pair caption: A typical AI handoff document. Same file, two views. # 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. | Format | What it is | Good at | Watch out for | |---|---|---|---| | Markdown (.md) | Plain text with symbols | Moving between tools and AI, staying tiny and readable by any app | Looks raw unless an app formats it | | Word (.docx) | A packaged rich document | Print layouts, tracked changes, sharing with people who use Word | Harder for AI tools to edit cleanly; formatting can drift | | Google Docs | A document stored in Google's cloud | Real-time collaboration | Lives online; exporting to .md can lose structure | | Apple Notes | Notes stored in the Notes app | Quick capture on all your Apple devices | Not a file you can hand to other tools easily | | PDF | A fixed page layout | Looking identical everywhere, printing | Hard to edit at all | | Plain text (.txt) | Text with no formatting rules | Maximum simplicity | No headings, tables or structure | 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 ### What does .md stand for? The .md in a file name stands for Markdown. The .markdown extension means the same thing, and some tools use .mdx or .mkd for variations. ### What app opens .md files on a Mac? Any text app can open a .md file on a Mac, including TextEdit, but it shows the raw symbols. A Markdown reader or editor shows the formatted page. ### Is Markdown the same as HTML? No, Markdown is not the same as HTML. Markdown is a simpler format that apps usually convert into HTML to display it. You can write a document in Markdown without knowing any HTML. ### Why do AI tools use Markdown? AI tools like Claude and ChatGPT use Markdown because it's plain text that keeps its structure, chat apps can display it as formatting, and other tools can read it back easily. ### Can I convert a .md file to PDF or Word? Yes, you can convert a .md file to PDF or Word. Many Markdown apps can export to PDF, and tools like Pandoc convert to Word. Keep the original .md if you'll share it with AI tools again. ### What does [!NOTE] mean in a Markdown file? [!NOTE] in a Markdown file marks a callout, a highlighted note. Apps that support GitHub-style callouts draw the quote below it as a colored box titled Note. Apps that don't show it as a normal quote with the label as text.