How to Create a Markdown (.md) File on Windows, Mac and Linux

To create a Markdown file, open a plain-text editor, write your text, and save the file with a .md extension, such as notes.md. Pick UTF-8 encoding when you save so letters and symbols display correctly.

A Markdown (.md) file is a plain-text file written in Markdown syntax. Plain text means the file holds only characters, with no hidden formatting like a Word document has. Syntax is the set of symbols, such as # for a heading, that tell a program how to format your text.

Programs called renderers read those symbols and display formatted output, like bold words or bullet lists. In Gruber's original Markdown announcement from March 2004, John Gruber described Markdown as "a text-to-HTML formatting tool." HTML is the code that web pages are built from.

The file extension is the part of a file name after the dot, and it tells your computer what kind of file it is. The RFC 7763 media type registration lists ".md" and ".markdown" as the file extensions for Markdown. RFC 7763 is an Informational document published in March 2016, not an Internet standard.

How to Create a Markdown File Step by Step

Every method in this section uses the same three steps: open a plain-text editor, write Markdown, and save as .md in UTF-8. Only the menus change between tools.

UTF-8 is a text encoding, which is a rule for storing letters as computer data. It can store any Unicode character, from accented letters to emoji, which helps your file show the same characters on Mac, Windows, and Linux.

Create a .md File in VS Code

Visual Studio Code (VS Code) is a free code editor from Microsoft that can create, edit, and preview Markdown files with no add-ons. VS Code was used by 70.9% of the survey's 13,193 respondents in the Stack Overflow 2026 IDE data.

1. Open VS Code and create a new file.
2. Type: # My First Markdown File
3. Save the file as README.md.
4. Open the preview with Ctrl+Shift+V (Windows/Linux) or ⇧⌘V (Mac).

The VS Code Markdown docs say to save the file with the .md extension, then toggle the preview with Ctrl+Shift+V (Windows/Linux) or ⇧⌘V (Mac). For a side-by-side preview, press Ctrl+K V (⌘K V on Mac).

The file encoding appears in the status bar, and clicking it lets you save with a different encoding, according to VS Code basic editing. Choose UTF-8 if the status bar shows something else.

Create a .md File on Windows With Notepad

Notepad is the plain-text editor built into Windows. If the save type stays on text documents, Notepad can turn notes.md into notes.md.txt. These steps are general advice that works in most Notepad versions, though menu labels can vary.

1. Type your Markdown in Notepad.
2. Open the Save As dialog.
3. Set "Save as type" to all files.
4. Type the file name, such as notes.md.
5. If an Encoding option appears, choose UTF-8, then save.

Windows may hide file extensions, so a notes.md.txt file can look like notes.md in File Explorer. Follow Microsoft's steps to Show file name extensions: in File Explorer, select View > Show > File name extensions.

Create a .md File on Mac With TextEdit

TextEdit is the Mac's built-in editor, and new documents open in rich text by default. Rich text stores hidden formatting, so switch to plain text before you write Markdown.

1. Open TextEdit and start a new document.
2. Choose Format > Make Plain Text.
3. Type your Markdown and save the file.
4. Rename the saved file so its name ends in .md, such as notes.md.

Apple's TextEdit plain text guide lists Format > Make Plain Text and says a plain text document saves as a .txt file. Renaming the file to .md is our own advice, so check the extension afterward.

To make plain text the default, choose TextEdit > Settings, click New Document, and select Plain text. Menu labels can vary by macOS version.

Create a .md File From the Command Line

The command line, also called the terminal, lets you create a file by typing a short command instead of clicking menus. On Mac and Linux, open the Terminal app; on Windows, open PowerShell.

# Mac and Linux
touch notes.md
echo "# Title" > notes.md

# Windows PowerShell
New-Item -Path notes.md -ItemType File
Set-Content notes.md "# Title"

The PowerShell New-Item docs describe New-Item as the cmdlet that creates files and folders in the file system. The PowerShell Set-Content docs say Set-Content writes new content or replaces the existing content in a file.

In PowerShell 7, Set-Content saves text as UTF-8 without a byte order mark (BOM) by default. If the file shows odd characters when you open it, check that its encoding is UTF-8.

Export a .md File From Google Docs

Google Docs can export a document as a Markdown (.md) file. Following the Google Docs Markdown export steps, open the document and select File > Download > Markdown (.md).

Open the downloaded file in a text editor to check the Markdown before you use it. Menu labels can vary by app version.

Basic Markdown Syntax to Put in Your File

Markdown syntax uses a few plain symbols to mark headings, emphasis, lists, links, and code. This table covers the elements most files need, so it works as a short Markdown cheat sheet.

The GitHub basic formatting syntax guide says to add one to six # symbols before heading text, and the number sets the heading level. The GitHub code block docs explain that an optional language identifier after the opening backticks enables syntax highlighting, as in bash in the sample.

A blank line between blocks, such as before a list, helps renderers keep them separate. This sample is a README.md, the file that introduces a project and appears on a GitHub repository's main page.

# My Project

A short Python script that saves web pages as Markdown files.

## Features

- Reads URLs from `urls.txt`
- Saves each page as a **.md** file

## Quick Start

1. Install Python 3.
2. Run the script:

```bash
python fetch_pages.py
```

## Status

| Feature | Ready |
|---|---|
| Single page | Yes |
| Full site | Planned |

## Docs

Read the [project docs](https://example.com/docs) for setup details.

Which Markdown Flavor Should You Write For?

Write for CommonMark when a file must render the same way in many tools. Write for GitHub Flavored Markdown (GFM) when the file lives on GitHub. A flavor is a version of Markdown with its own rules.

Gruber's original description left some rules unclear, so tools began formatting the same text in different ways. The CommonMark specification defines those rules in detail, and its latest version is 0.31.2, dated January 28, 2024.

The GitHub Flavored Markdown spec states that GFM is a strict superset of CommonMark, so every CommonMark rule still applies. GFM adds extensions, including tables, task lists, strikethrough, and autolinks. The current GFM spec version is 0.29-gfm.

• README on GitHub: Use GFM, since GitHub renders its tables and task lists.
• Docs for many tools: Stick to CommonMark syntax for the most predictable output.
• Files for AI tools: Use headings, lists, and code blocks, which both flavors share.

How to Create a Markdown File From a Web Page

To create a Markdown file from a web page, run the page through a converter and save the output as a .md file. Copying and pasting often fails, because you either paste rich text or lose the headings, links, and tables.

HTML to Markdown conversion rewrites a page's HTML tags as Markdown syntax. A good converter also strips boilerplate, which is the repeated parts of a page that are not the main content. Olostep returns Markdown by default and removes boilerplate automatically:

• Removed: Navigation, ads, popups, scripts, and cookie banners.
• Kept: Article content, headings, lists, tables, and links.

For a single page without code, Olostep's website to Markdown converter turns a URL into Markdown. Paste the output into any editor from the steps above and save it as page.md.

For many pages or repeat jobs, use an API, which lets your code send a request to a service and get data back. The Olostep Scrape endpoint accepts a URL and returns the page as Markdown.

This Python example needs Python 3 and the requests library, which you can install with pip install requests. Replace <API_KEY> with your Olostep API key before you run it.

import requests

url = "https://example.com/blog/post"

response = requests.post(
    "https://api.olostep.com/v1/scrapes",
    headers={"Authorization": "Bearer <API_KEY>"},  # replace <API_KEY> with your key
    json={"url_to_scrape": url, "formats": ["markdown"]},
    timeout=60,
)
response.raise_for_status()
data = response.json()

# Markdown is in result.markdown_content; confirm in the Scrape endpoint docs.
markdown_text = data["result"]["markdown_content"]

with open("page.md", "w", encoding="utf-8") as f:
    f.write(markdown_text)

print("Saved page.md")

The API sends back JSON, a structured data format. The Olostep Create Scrape API reference lists markdown_content inside the response's result object when you request the markdown format.

To turn many pages into files, use Olostep's Crawl endpoint to crawl an entire docs site and discover its subpages. Each crawled page has a retrieve_id, which you pass to the Olostep Retrieve Content API in a separate call to get that page's Markdown.

Save each page's Markdown as its own .md file, named after the page path. Only scrape pages you have permission to use, and follow each site's terms and robots.txt rules.

Markdown Files for AI Agents and LLMs

Markdown is a common format for AI instructions and reference files, since headings and lists give plain text a clear structure. A large language model (LLM) is the type of AI behind tools like ChatGPT and Claude. An AI agent is an LLM that can take actions, such as editing code.

• AGENTS.md: The AGENTS.md open format describes this file as a README for agents, written in standard Markdown at a project's root.
• CLAUDE.md: The Claude Code memory docs say Claude Code reads it as persistent project instructions, treated as context rather than enforced rules.
• llms.txt: A Markdown file at a website's /llms.txt path that lists links to the site's LLM-friendly pages.

The llms.txt proposal suggests adding a /llms.txt Markdown file to websites to provide LLM-friendly content. It is a community proposal, not a formal web standard.

Olostep's explainer covers what llms.txt files do and how sites structure them. To draft one for your site, try Olostep's free llms.txt generator.

A token is a small piece of text, often part of a word, that an LLM processes. Many AI services charge per token, so shorter input can cost less. Markdown can use fewer tokens than HTML for the same page, because it drops most of the tags.

One example comes from Cloudflare Markdown for Agents: a single blog post took 16,180 tokens in HTML and 3,150 tokens in Markdown. That result covers one page measured by one vendor, so savings on other pages will differ.

Headings also help RAG (retrieval-augmented generation) systems, which find passages in your documents and pass them to an LLM as context. These systems split files into chunks, and clear H2 and H3 headings mark natural places to split. Olostep's guide to RAG chunking strategies explains how to split documents for retrieval.

How to Check Your .md File Works

A working .md file has the right extension, opens as plain text, and renders correctly in a preview. To open an md file, use any text editor for the raw text, or a Markdown preview for formatted output.

1. Confirm the extension: Run ls (Mac/Linux) or dir (Windows) and look for notes.md, not notes.md.txt.
2. Open it as plain text: Open the file in Notepad or TextEdit and check that you see the # and * symbols.
3. Preview the render: Open the file in VS Code and press Ctrl+Shift+V (Windows/Linux) or ⇧⌘V (Mac).

If a check fails, find your symptom in this list. Each line names the problem and the fix.

• Name ends in .md.txt: Rename the file, delete .txt, and confirm the change when Windows asks.
• Text shows strange symbols: Re-save the file with UTF-8 encoding.
• File starts with {\rtf1: The file was saved as rich text, so re-save it as plain text in TextEdit.
• Heading shows as plain text: Add a space after the # signs, as in # Title.
• List merges into a paragraph: Add a blank line before the first list item.

FAQ

These answers cover questions that come up after you create your first .md file. They focus on opening, naming, and converting Markdown files.

What Program Opens a .md File?

Any text editor opens a .md file, including Notepad, TextEdit, and VS Code. To see the formatted version, use a Markdown preview such as the one in VS Code, or view the file on GitHub.

Why Did My File Save as .md.txt?

Your editor likely added .txt because the save type was set to text documents, and Windows may hide the extra extension. Save again with the save type set to all files, or rename the file to end in .md.

What Is the Difference Between .md and .markdown?

Both extensions mark the same plain-text format, and RFC 7763 lists both for Markdown files. Common project files, such as README.md and AGENTS.md, use the shorter .md.

What Does ``` Mean in Markdown?

Three backticks open and close a fenced code block, which shows text exactly as typed in a fixed-width font. Adding a language name after the opening backticks, like ```python, can turn on syntax highlighting, depending on the renderer.

Is Markdown Better Than HTML?

Markdown is faster to write and easier to read as plain text, while HTML gives full control over layout and styling. Markdown renderers convert your file into HTML, so you can write in Markdown and still publish a web page.

Can I Convert a Word or Google Doc to Markdown?

Yes: Google Docs exports via File > Download > Markdown (.md), and Pandoc, a free, open-source converter, handles Word with pandoc input.docx -t gfm -o output.md. The Pandoc user's guide lists docx as an input and gfm as an output, and the conversion may lose some formatting.