What is an .md file?
Author: Domeny.ForSale editorial team Published
In brief: An .md file is usually a plain text file written in Markdown — a simple way to mark headings, lists, links and other document elements. You can open it in any text editor, while a program that supports Markdown will also display a formatted version. These files are often used to create instructions, notes, documentation and website content.
What does the .md extension mean?
The .md extension, the ending of a file name, usually indicates Markdown. This is a lightweight markup language: instead of selecting formatting from a toolbar, you type simple symbols into the text. For example, two asterisks on either side of a word indicate bold text.
The document remains readable even without a special program. In a text editor, you will see the words and markup; in a Markdown preview, you will see the formatted content. The process of turning markup into the document’s visual appearance is called rendering.
Unlike a .docx file, a Markdown document does not store a complex page layout, such as precise positioning of elements or print settings. It focuses on content and structure. However, the extension alone does not guarantee what is inside: a file can be given any name, so an unusual .md document may not contain valid Markdown text.
How do you open an .md file and view its formatting?
A plain text editor, such as the built-in Notepad application, is enough to read the content. This is a good option if you want to check some instructions quickly or correct a single sentence. You will also see the symbols responsible for formatting.
For a more convenient way to work, choose a tool with a Markdown preview:
- Visual Studio Code lets you edit the source and display a preview of the document.
- Obsidian is suitable for keeping and linking notes stored in Markdown files.
- Typora lets you work with content in a view that resembles the finished document.
- GitHub displays the formatted content of Markdown files stored in repositories, which are collections of project files.
If double-clicking the file does not launch the right program, use the “Open with” command and select a text editor. You do not need to change the extension to .txt. A web browser alone will not always display a local .md file with formatting — it may show the raw content or offer to download it.
What does Markdown syntax look like in practice?
You can learn the basic markup with a short note. The following example contains a second-level heading, bold text, a list and code markup:
## Preparing the website
**Before publishing**, check:
- that the contact details are correct,
- that the form works,
- how the website looks on a phone.
The project's starting file is `index.html`.
In the preview, the ## symbols will be replaced by heading formatting, the asterisks will make the words bold, and the hyphens will create a bulleted list. The backticks around index.html will distinguish the name as a snippet of code. A blank line separates paragraphs or larger blocks of content.
A link is written using the pattern link text, and an image using the pattern image description. An image is usually not embedded in the .md document itself: the markup points to its location. When moving the document, you therefore also need to take care of the image files and make sure the paths are correct.
There are different flavours of Markdown, meaning different sets of rules for interpreting markup. Basic headings and lists are widely supported, but tables, task lists and footnotes may work differently depending on the program. If the document is intended for a particular system, check the preview in that system.
How do you create an .md file and share it with someone else?
You can prepare a new document without installing specialist software:
- Open a plain text editor and enter the content with Markdown markup.
- Choose to save it as a text file, preferably with UTF-8 encoding to preserve Polish characters.
- Give it a name, for example
instructions.md. - Check that the program has not automatically added the
.txtextension, creatinginstructions.md.txt. - Open the document in a Markdown preview and check the formatting.
Renaming a Word file from instructions.docx to instructions.md does not convert the document. You need to export the content with an appropriate tool, or paste it as plain text and add the markup.
If the recipient needs to edit the instructions, send the .md file along with any images used. If they only need to read the finished material, a PDF exported from a program that supports Markdown may be more convenient. The available export formats depend on the tool you choose.
When is Markdown a good choice?
Markdown works well wherever content matters more than visual layout: in notes, instructions and technical documentation. The widely used README.md file usually describes a project, how to run it or how to use it. Because it is plain text, it is easy to compare successive versions and identify changed sentences.
Files with the .md extension can also serve as the source for articles in website generators such as Hugo. These systems turn the content into a web page and style it according to a template. However, a Markdown file on its own is not a finished website.
For a document that requires a precise print layout, complex tables or manual positioning of elements, a word processor or page layout program will be a better choice. To get started, create a short .md note and open it both as text and in a preview — you will immediately see the difference between the markup and its effect.
See also: What is 2FA?
Read also
