How to Create a Markdown File
Create your first .md file in 2 minutes — no special tools needed
Markdown is the simplest way to write formatted text. You type plain characters like #, **, and -, and they turn into headings, bold text, and lists when rendered. If you've ever written a message on GitHub, Reddit, or Discord, you've already used Markdown. This guide shows you how to create a .md file from scratch. Already know the basics? Jump to our Markdown cheat sheet for a quick reference.
How to Create an .md File on Mac
macOS has no “New Markdown file” menu item, but you need nothing extra. Pick one of three ways:
With TextEdit (built in)
- Open TextEdit and choose File → New.
- Choose Format → Make Plain Text (⇧⌘T). Without this step TextEdit saves rich text, not Markdown.
- Type your Markdown, for example
# My notes. - Choose File → Save, name the file
notes.mdand click Save. When TextEdit asks about the extension, click Use .md.
With Terminal
cd ~/Documents
touch notes.md
open notes.md
touch creates an empty file; open opens it in your default app for .md files.
With VS Code or another editor
Press ⌘N, write your text and save with ⌘S as notes.md. Any code or text editor works the same way.
Check the extension and open the file
If Finder hides extensions, the file may really be called notes.md.txt. Turn on Finder → Settings → Advanced → Show all filename extensions to be sure, and rename it if needed. To read the file with headings, lists and tables formatted instead of raw # and **, open it in a Markdown viewer such as MDViewer — see how to open .md files on Mac.
Step 1: Create a .md File
A Markdown file is just a plain text file with a .md extension. You can create one in any text editor:
- Mac Terminal:
touch README.md - VS Code: File → New File → save as
notes.md - TextEdit: switch to plain text mode (Format → Make Plain Text), then save with
.md— step by step in the Mac section above - Finder: right-click → New File (if you have a file creation tool) → rename to
.md
Starting from an existing document? Convert it instead of retyping: Word to Markdown, PDF to Markdown or HTML to Markdown.
Common filenames: README.md (project docs), CHANGELOG.md (release notes), notes.md (personal notes), TODO.md (task lists). Not sure what a .md file is? See What Is an .md File?
Step 2: Write Your Content
Here are the building blocks you'll use in every Markdown file:
Headings
# Main Title ## Section ### Subsection
Use one # for the document title, ## for sections, ### for subsections. Most documents only need these three levels.
Text formatting
This is a paragraph. Leave a blank line between paragraphs. **Bold text** for emphasis. *Italic text* for titles or terms. ~~Strikethrough~~ for corrections.
Lists
- First item - Second item - Nested item 1. Step one 2. Step two 3. Step three - [x] Task complete - [ ] Task pending
Links and images
[Link text](https://example.com) 
Code
Inline code: `npm install`
Code block with syntax highlighting:
```python
def greet(name):
return f"Hello, {name}!"
```
Tables
| Name | Role | Status | |---------|------------|--------| | Alice | Developer | Active | | Bob | Designer | Active |
For alignment, multi-line cells, and advanced tricks, see the Markdown Tables Guide.
Blockquotes
> This is a blockquote. Use it for > callouts, notes, or quoted text.
Step 3: Preview Your Markdown
You've written your content — now see how it looks rendered:
- MDViewer — open your .md file and see it rendered with full formatting, Mermaid diagrams, and syntax highlighting. Set it as your default app to double-click and open
- Quick Look — select the file in Finder and press Space for an instant preview (with MDViewer's QuickLook extension)
- Online viewer — drag your file into the browser. No install needed, works on any OS
- VS Code — press ⌘⇧V to open a side-by-side preview pane
For all preview options, see Markdown Preview on Mac.
Your First Complete .md File
Here's a complete example that uses everything above — copy it, save as README.md, and open in MDViewer to see the result:
# My Project
A short description of what this project does.
## Installation
```bash
npm install my-project
```
## Usage
```js
import { doThing } from 'my-project'
doThing()
```
## Features
- **Fast** — runs in under 10ms
- **Simple** — one function, zero config
- **Tested** — 100% code coverage
## Contributing
1. Fork the repo
2. Create a branch
3. Open a pull request
## License
MIT
For more templates (library, CLI, app, API), see README.md Templates.
Where Markdown Is Used
- GitHub / GitLab / Bitbucket — README files, pull request descriptions, issues, wikis
- AI tools — ChatGPT, Claude, and Cursor generate Markdown output. See why AI tools use Markdown
- Documentation — MkDocs, Docusaurus, Jekyll, and Hugo all use .md files
- Note-taking — Obsidian, Bear, Notion (export), Apple Notes (partial)
- Messaging — Slack, Discord, Reddit, and Stack Overflow support Markdown formatting
Get MDViewer
Write in any editor, preview in MDViewer — a native macOS app with Quick Look, Mermaid diagrams and a table of contents. The Lite version is free for personal use; Pro ($9.99 one-time) adds inline editing, Git history and PDF export.
Requires macOS 13.0 or later. Intel and Apple Silicon.
Frequently Asked Questions
How do I create a Markdown file?
Open any text editor (TextEdit, VS Code, Notepad), create a new file, and save it with the .md extension — for example README.md. Markdown files are plain text, so any editor works. No special software is needed.
What app should I use to write Markdown on Mac?
Any text editor works — VS Code, Sublime Text, or even TextEdit (in plain text mode). For previewing what you write, use MDViewer: it renders your .md file with full formatting, tables, code highlighting, and Mermaid diagrams.
How do I create an .md file on Mac?
Open TextEdit, choose Format → Make Plain Text, type your text and save it as notes.md, then click Use .md when asked. In Terminal, run touch notes.md. Any code editor such as VS Code works too — just save the file with the .md extension. Details in How to Create an .md File on Mac.
Why did my Markdown file save as .md.txt?
TextEdit adds .txt when the document is still rich text or when the extension prompt is answered with “Use .txt”. Switch to plain text (Format → Make Plain Text), save again and choose Use .md. Turn on Finder → Settings → Advanced → Show all filename extensions to see the real name.
Is Markdown the same as HTML?
No. Markdown is a simpler alternative to HTML. Instead of writing <h1>Title</h1>, you write # Title. Markdown gets converted to HTML for display, but it's much easier to read and write. Most platforms (GitHub, Reddit, Discord) accept Markdown directly.
Can I convert Markdown to PDF?
Yes. MDViewer Pro can export any .md file to PDF with smart pagination. You can also use Pandoc from the command line or browser print-to-PDF from any online Markdown viewer.