How to Create a Markdown File (Step by Step, Any OS)

Here's how to create a markdown file: open any plain text editor, type your content, and save it with the .md extension instead of .txt. That's the whole trick. This tutorial walks through the exact clicks on Windows, macOS, VS Code, the terminal, GitHub, and an online editor, plus a copy-ready starter file.

What Is a Markdown File, Mechanically?

A Markdown file is a plain text file. There's no binary container, no hidden formatting, and no app that "owns" it the way Word owns .docx. The symbols you type (# for a heading, ** for bold) are the formatting, and a separate program called a renderer turns them into styled output.

That split confuses beginners. Markdown isn't software you install. It's a writing convention, and the file it produces is identical to a text file except for the name. RFC 7763, which registered the text/markdown media type in March 2016, lists .md and .markdown as the extensions. In practice almost everyone uses .md.

If you want the concept before the mechanics, our plain-English explanation of Markdown covers it. The rest of this post assumes you know why and just need the file to exist.

A Starter File Showing How to Write Markdown

Type or paste this into whichever editor you pick below and save it as README.md. You now have a working Markdown file that renders on GitHub, in VS Code, and in every note app. Learning how to write in Markdown takes about ten minutes; this file uses the five symbols you'll need most.

# Project Notes

A one-paragraph description of what this file is for.

## To do

- Write the introduction
- Add a link to the [docs](https://example.com)
- Test the code sample below

## Sample

```bash
echo "hello"
```

Rendered, that gives you a large heading, a paragraph, a smaller heading, a three-item bullet list with one link, and a grey code box. For every other symbol, keep the Markdown cheat sheet open in another tab.

How Do I Create a .md File on Windows?

Notepad works, with one trap in the save dialog. The steps below are for the Windows 11 Notepad app; the older Notepad on Windows 10 behaves the same way in the dialog.

1. Open Notepad and type your content.
2. Press Ctrl+S. In the Save As dialog, set Save as type to All files.
3. Type the name with the extension, for example notes.md, and click Save.

Skip step 2 and Notepad quietly appends .txt, leaving you with notes.md.txt. Because Explorer hides known extensions by default, the file then looks like notes.md while still being a text file. Turn on File name extensions in Explorer's View menu once and you'll never be fooled again.

Since Notepad version 11.2504.52.0 (mid 2025) the app also has Markdown formatting built in. With the Formatting toggle on in Settings, File > New Markdown tab creates an .md file, and the View menu (or the toggle in the status bar) switches between the raw Markdown syntax and a formatted preview. The file on disk stays plain text either way. Encoding defaults to UTF-8 without a byte order mark, which is what every renderer expects.

How Do I Create a Markdown File on a Mac?

TextEdit opens in rich text mode by default, and rich text saved to disk is RTF, not Markdown. Fix that before you type.

1. Open TextEdit and create a new document.
2. Choose Format > Make Plain Text (Shift+Cmd+T). The ruler disappears.
3. Type your content, press Cmd+S, name the file notes.md, and confirm you want .md instead of .txt if TextEdit asks.

To skip step 2 forever, open TextEdit's settings and set new documents to plain text, an option Apple documents in the TextEdit User Guide. Our preference on a Mac is still VS Code or the terminal, because neither can accidentally save rich text.

Create a Markdown File in VS Code or the Terminal

VS Code treats .md as a first-class language and ships a preview, so it's the editor most tutorials assume.

1. Press Ctrl+N (Cmd+N on Mac) for an untitled file.
2. Press Ctrl+S, type notes.md, and save. The status bar switches to "Markdown" and syntax colouring turns on.
3. Press Ctrl+Shift+V (Cmd+Shift+V) to open the rendered preview, or Ctrl+K then V to put it beside the editor.

The VS Code Markdown docs confirm those shortcuts and note that the preview uses the markdown-it library, which follows CommonMark. For extensions, linting, and preview settings, our VS Code Markdown guide goes deeper.

Prefer the terminal? One command creates the file; a second one puts a heading in it. These work in macOS Terminal, any Linux shell, and Git Bash on Windows.

touch notes.md
echo "# Notes" > notes.md

PowerShell users can run New-Item notes.md, and the classic Windows command prompt accepts type nul > notes.md. To edit inside the terminal, nano notes.md opens a minimal editor; Ctrl+O saves and Ctrl+X exits.

Create a Markdown File Online or on GitHub

If you've been searching how to make a markdown file on a locked-down work machine, a Chromebook, or a phone, use a browser editor. In our editor, type or paste your content, watch the preview on the right update as you go, then open the Download / Export menu and choose Download .md. The browser saves a real .md file you can commit, email, or drop into Obsidian.

The same menu exports PDF, HTML, and DOCX if the person you're sending it to doesn't read Markdown. Try it now; the starter file is already loaded below.

echo hello

GitHub also lets you create the file without leaving the browser, which is handy for a first README.

1. Open the repository and click Add file > Create new file.
2. Type README.md as the name. The editor gains a Preview tab once the name ends in .md.
3. Paste your content, check the Preview tab, and commit.

GitHub's README documentation says a README in the root, docs, or .github folder is surfaced automatically on the repository page. Our README guide covers what to put in it.

Encoding, Line Endings, and Where to Save

Three details rarely cause problems, but when they do they're baffling.

Encoding. Save as UTF-8. Notepad, TextEdit, and VS Code all default to it now. An older Windows tool may write UTF-16 or add a byte order mark, which shows up as stray characters at the top of a rendered page.

Line endings. Windows editors write CRLF, everything else writes LF. Markdown renderers don't care, and Git normalises them if you set core.autocrlf. The one limitation to remember: a Markdown line break needs two trailing spaces or a backslash, and some editors strip trailing spaces on save.

Location. However you create markdown files, keep them next to what they describe: README.md in the project root, notes in a folder you sync. Tools like Obsidian and AI coding assistants read plain .md files straight from a folder. A CLAUDE.md or AGENTS.md file for an AI tool is created exactly the same way; there's no special format beyond ordinary Markdown.

Common Markdown File Creation Mistakes

The double extension. notes.md.txt from Notepad's default save type. Fix: choose All files, or rename the file with extensions visible.

Rich text on the Mac. A TextEdit document saved before Make Plain Text is RTF, and renderers show {\rtf1\ansi gibberish. Fix: convert to plain text, then Save As with the .md name.

Writing in Word and renaming. Word inserts smart quotes, non-breaking spaces, and its own list markers. Renaming notes.docx to notes.md changes nothing; you'd need to convert it. Our DOCX to Markdown tool does that conversion properly.

Markdown File FAQ

That's how to create a markdown file on every platform: plain text, .md extension, UTF-8, and a renderer to check the result. Start with the starter file above and keep the cheat sheet handy for syntax. When you don't want to install anything, write it in the editor, preview it live, and download the .md when it looks right.