What is Markdown, and how do you read a .md file?

Somebody has sent you a file ending in .md, or you are looking at text peppered with asterisks, hashes and square brackets: **like this**, # like that. At first glance it looks broken. It is not broken, it is formatted, and the way of writing is called Markdown.

The idea behind it is straightforward. Instead of reaching for buttons to format text, you write the formatting into the text with a handful of marks. A word wrapped in asterisks becomes bold; a line beginning with a hash becomes a heading. A program that understands the marks turns the file into a tidy document, and a program that does not still shows readable text, because nothing is hidden inside it.

How to open a .md file

A Markdown file is nothing but ordinary writing, which means any text editor will open it. Start the editor, choose Open from the File menu, and set the file-type box in the corner of the dialogue to "All files" — while that box says "Text documents", your .md file will not appear in the list at all. What you get is the whole file, marks and all.

To see it laid out rather than raw, you have two options. You can open it in an application that understands Markdown: plenty of note-taking apps, code editors and repository sites render it the moment the file loads. Or you can convert the text to HTML and open that in a browser, which is the more useful route when you need to send the document on or drop it into a web page.

If you cannot see the extension at all — the file name does not end in .md on screen — tick "File name extensions" under the View tab in File Explorer on Windows. Seeing the extension is the quickest way to work out which program a file belongs to.

The marks you will actually meet

You do not need to learn all of Markdown; nearly all everyday writing runs on the marks below. Reading the table once is enough to decode anything that lands in front of you.

Watch one detail: most of these marks go at the very start of the line and are followed by a space. Leave the space out between the hash and the heading text and the line stays exactly as you typed it.

Where Markdown turns up

Because Markdown carries its formatting inside the text, that formatting can never be stripped out in transit. This is why it is preferred wherever writing passes from hand to hand.

You will meet it most often in software repositories: the README file that introduces a project is Markdown almost without exception. Beyond that, note-taking apps, team wikis, forums, chat applications and blog engines all use the same notation. Those asterisks in text you copy out of an AI chat are the same thing.

Set against a word processor, the difference is this. In a Word document the formatting lives somewhere you cannot see, and the program opening the file has to understand it. In Markdown the formatting is right in front of you. The price is that elaborate layouts — multiple columns, footnotes, page numbers — simply do not exist in Markdown; it was designed for short, flat documents.

Converting the text to HTML

If the text is headed for a web page, a content management system or the body of an email, one translation step sits in the middle: HTML. Paste the text into the Markdown to HTML tool and the headings, lists and links become the corresponding tags.

You choose between two kinds of output. The body output gives you the content tags only, which is what you want when pasting into an existing template. The full-page output produces a working file that a browser will open on its own.

The tool's scope is the everyday core: headings, bold, italic, lists, quotations, links and code. Tables, images and nested lists fall outside it and come through as plain text rather than disappearing quietly. If your document contains them, look over the output and finish those parts by hand.

Tables: the standard and its dialects

The core definition of Markdown has no tables at all. Tables arrived later, through extensions that particular platforms added, which is why the same table can render properly in one place and come out as line after line of plain text in another. Check where you intend to publish before you write one.

The notation builds columns out of vertical bars and requires a divider line immediately under the heading row. Writing that by hand gets tiresome after a few rows, and the alignment slips easily.

If your data is already in a table, there is a shorter route: save it as CSV and pass it through the CSV to Markdown Table tool. You can paste the result straight into a README or a wiki page, and because the cells are padded to the column width, it stays readable even before it is rendered.

Four mistakes people keep making

Markdown's marks are simple, so the mistakes cluster in the same few places. When a piece of text does not look the way you expected, check these first.

• The missing space: there must be a space between the hash and the heading text, and between the dash and the item text. "#Heading" is not a heading; "# Heading" is.
• Lines running together: two lines typed one under the other count as a single paragraph in most environments. If you want separate paragraphs, leave a blank line between them.
• When an asterisk is genuinely an asterisk: one used as a footnote marker or in a price list can be mistaken for formatting. Put a backslash in front of it (\*) and it stays as typed.
• Confusing images with links: notation starting with a square bracket is a link; put an exclamation mark in front and it becomes an image. Forget the exclamation mark and you get a link to the picture's address instead of the picture.

Frequently asked questions

What is Markdown used for?

It is a plain way of writing in which the formatting is expressed inside the text itself with a few marks. A word between asterisks is bold; a line starting with a hash is a heading. Because the file is plain text it opens anywhere, and the formatting cannot be lost along the way.

How do I open a .md file?

In a text editor, choose Open from the File menu and set the file-type box to "All files"; the file is ordinary writing. To see it laid out, open it in an application that understands Markdown, or convert the text to HTML and view that in a browser.

How do I convert Markdown to HTML?

Paste the text into the Markdown to HTML tool and the headings, lists and links become tags. Choose the body output when you are pasting into an existing template, and the full-page output when you need a standalone file a browser can display by itself.

Can I write tables in Markdown?

Not in the core definition; tables come from extensions that particular platforms added, so they do not render the same everywhere. If your data is already tabular, saving it as CSV and using the CSV to Markdown Table tool is the shortest route.

What is the difference between Markdown and Word?

In Word the formatting is stored somewhere you cannot see; in Markdown it sits in the text, in plain sight. Markdown travels better, but it has no support for elaborate layouts such as multiple columns, footnotes or page numbers.

Last updated: August 27, 2026