Documents & text · File type

What is a .md file?

A .md file is a plain-text document written in Markdown, a lightweight syntax where # makes headings, * makes lists and [text](url) makes links. It is the standard for README files, documentation sites, wikis, static-site blogs and notes apps.

Key facts

Plain UTF-8 text that stays readable as-is and is converted to HTML for display.
MIME type is text/markdown (RFC 7763); .markdown is an alternative extension.
CommonMark is the strict specification; GitHub Flavored Markdown (GFM) adds tables, task lists, strikethrough and autolinks.
Renderers differ, so the same file can look different on GitHub, GitLab, VS Code and static-site generators.
Many files start with YAML front matter between --- lines for title, date and other metadata.

How to open a .md file

Windows

Open it in VS Code and press Ctrl+Shift+V for a live preview, or use a Markdown app such as Obsidian or Typora. Notepad shows the raw text.

macOS

Open it in VS Code (Cmd+Shift+V to preview), Obsidian or MacDown; TextEdit shows the raw text.

Linux

Read it with less README.md, preview it in VS Code, or render it with pandoc README.md -o README.html.

Common problems and fixes

Table shows as plain text with pipes: Tables are a GFM extension and need a header separator row like | --- | --- | and a blank line before the table. Check that your renderer supports GFM tables.
Line breaks disappear: Markdown joins consecutive lines into one paragraph. Leave a blank line between paragraphs, or end a line with two spaces or a backslash for a hard break.
Images or links are broken: Relative paths are resolved from the file's location, and spaces in paths must be encoded as %20 or wrapped in < >. Check the path and the case of the file name, because servers are case-sensitive.
Code blocks or lists render wrongly: Fenced code needs a blank line before ``` and a matching closing fence, and nested list items need consistent indentation. Fix indentation to match the parent item's text.

Often converted to or from: HTML, PDF, DOCX, Markdown table from CSV, plain text

File2fix tools for .md files

Markdown to HTML Converter →Markdown Link & Image Checker →Markdown Table Master →Local Data, Text, and Image Converter →Word & Character Counter →

Frequently asked questions

How do I view a .md file as formatted text?

Use a Markdown previewer such as VS Code's built-in preview, Obsidian or Typora, or push it to GitHub, which renders README.md automatically. Any text editor shows the raw syntax.

How do I convert Markdown to PDF or Word?

Pandoc is the most flexible option: pandoc file.md -o file.docx, or -o file.pdf with a LaTeX engine installed. Typora and VS Code extensions can also export to PDF.

What is the difference between .md and .txt?

Both are plain text, but .md tells editors and websites to interpret Markdown syntax and render headings, links and formatting. A .txt file is always shown as-is.