MD: Markdown

The programmer's writer.

Markdown & TextMarkdownWritingFormatting

Learn how to write beautifully formatted documents without your hands ever leaving the keyboard using Markdown syntax.

getbetterat.work

Technical Guide

File Format Series

What is an .md file?

An .md file is a Markdown document. It is a very simple text file that lets you format text using basic keyboard symbols.

Instead of clicking buttons to make text bold or create lists (like you do in Microsoft Word), you just type symbols like stars (*) or hashes (#). This makes writing very fast.

Why people love Markdown

Never Leave the Keyboard

You do not need to use your mouse to click formatting buttons. You can write your thoughts down as fast as you can type.

It works everywhere

It is just plain text. A Markdown file written today will still open on any computer 50 years from now. You are never locked into one app.

Turns into Websites

Computers can easily read Markdown and turn it instantly into clean HTML (the code that builds websites). This makes it perfect for blogs.

How does it work?

The process is simple. You write plain text with special symbols. A program reads it, and shows it to you as nicely designed text.

**Hello**

1. You type this

Hello

2. You see this

The Syntax Cheat Sheet

Learn the rules

Here is exactly how to type different formats using Markdown. The dark box shows what you type. The light box shows the result.

Titles and Headings

# Big Title ## Medium Title ### Small Title

Big Title

Medium Title

Small Title

Text Styles (Bold & Italic)

**This is bold text** *This is italic text* ~~This has a line through it~~

This is bold text

This is italic text

~~This has a line through it~~

Making Lists

- First item - Second item - Third item 1. Step one 2. Step two 3. Step three

First item
Second item
Third item

Step one
Step two
Step three

Links to Websites

Go to [Google](https://google.com) to search.

Go to Google to search.

Showing Code Elements

If you write instructions for computer programs, Markdown is the best tool. You use the "backtick" symbol ( ` ) to show code.

Press the `ENTER` key. ``` function sayHello() { print("Hello!") } ```

Press the ENTER key.

function sayHello() {
print("Hello!")
}

Quoting People

> "Keep it simple and clean."

"Keep it simple and clean."

Adding Images

![A cute cat](cat.jpg)

Making Task Lists (Checkboxes)

- [ ] Buy milk - [x] Walk the dog - [ ] Read a book

Buy milk

Walk the dog

Read a book

Drawing Tables

| Name | Age | Job | |-------|-----|---------| | Sarah | 25 | Writer | | Mike | 30 | Builder |

Name	Age	Job
Sarah	25	Writer
Mike	30	Builder

Dividing Lines

Section One --- Section Two

Section One

Section Two

Where do people use Markdown?

You might be using Markdown right now without knowing it. Many popular websites use it so you can type messages quickly.

GitHub (README files)

Reddit Comments

Discord Chat

Blogging Platforms

The Magic Backslash

What if you actually want to type a star (*) without making the text bold? You use a backslash (#) right before the symbol. This tells the computer to ignore the rule.

Type: \*This is not italic\*

Result: *This is not italic*

Common Mistakes for Beginners

Don't do this

Forgetting the space in headings.

#My Title

This will just look like plain text with a hash in front of it.

Do this instead

Always add a space after the hash.

# My Title

This will correctly turn into a giant, bold heading.

Secret Trick: You can mix HTML

Markdown is not meant to replace HTML perfectly. If Markdown cannot do something (like making text red, or centering a picture), you can just type standard HTML right in the middle of your Markdown file!

This is regular markdown.
<br>
<span style="color: red;">But this is red HTML text!</span>

Different "Versions" of Markdown

Markdown was invented in 2004. Over the years, people added new features to it. We call these different versions "Flavors". They all share the same basics, but some have extra powers.

Original

Standard Markdown

The very first version. It is very simple but does not support things like tables or task lists.

GFM

GitHub Flavored Markdown.

This is what most people use today. It adds tables, checklists, and strikethrough text.

MultiMarkdown

A heavy-duty version used by professional writers to make footnotes, math equations, and book chapters.

How do I turn it into a PDF?

You cannot send a `.md` file to someone who does not know what it is. You need to convert it. Most writing apps (like Obsidian or Typora) have an "Export" button.

your_file.md

Click "Export" in App

your_file.pdf

The 3 Golden Rules

Always leave blank lines

Markdown relies on empty space. If you want a new paragraph, press ENTER twice. If things look broken, you probably forgot a blank line.

Use standard fonts when writing

Don't try to make the `.md` text look fancy while you are typing it. Use a clear, simple font. Let the app make it look pretty when it is finished.

It is okay to forget

Nobody remembers all the symbols. It is completely normal to keep a cheat sheet open on your screen while you learn.

Best Tools to Write Markdown

Because Markdown is just text, you can write it in Windows Notepad or Apple TextEdit. However, special apps make it look prettier while you type.

Tool Name	Best For	Price
Obsidian	Taking personal notes and linking ideas.	Free
VS Code	Programmers writing software documentation.	Free
Typora	Writers who want a very clean screen.	Paid

You are ready to write.

Do not try to memorize everything. Just start using a few hashes (#) for your titles and stars (*) for bold text. You will get used to it in no time.

MD: Markdown

Big Title

Medium Title

Small Title

Always leave blank lines

Use standard fonts when writing

It is okay to forget

More in this series

Data Engineering

Spreadsheets

Presentations

Word Processing

Digital Publishing

Software Engineering

Markdown & Text