How to Write 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.

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
  • Finder: right-click → New File (if you have a file creation tool) → rename to .md

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

Markdown
# Main Title
## Section
### Subsection

Use one # for the document title, ## for sections, ### for subsections. Most documents only need these three levels.

Text formatting

Markdown
This is a paragraph. Leave a blank line between paragraphs.

**Bold text** for emphasis.
*Italic text* for titles or terms.
~~Strikethrough~~ for corrections.

Lists

Markdown
- First item
- Second item
  - Nested item

1. Step one
2. Step two
3. Step three

- [x] Task complete
- [ ] Task pending

Links and images

Markdown
[Link text](https://example.com)
![Alt text](images/screenshot.png)

Code

Markdown
Inline code: `npm install`

Code block with syntax highlighting:

```python
def greet(name):
    return f"Hello, {name}!"
```

Tables

Markdown
| Name    | Role       | Status |
|---------|------------|--------|
| Alice   | Developer  | Active |
| Bob     | Designer   | Active |

For alignment, multi-line cells, and advanced tricks, see the Markdown Tables Guide.

Blockquotes

Markdown
> 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:

README.md
# 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. Free, native macOS app with Quick Look, Git history, Mermaid diagrams, and inline editing.

Download MDViewer for Free

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.

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 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.