What Is Markdown? Syntax, Links, and Examples

Markdown is a lightweight markup language for formatting plain text. You add simple characters such as #, *, and []() to describe a heading, emphasis, or link. A Markdown app then renders that source as a formatted document, web page, or PDF.

The key advantage is that the source remains readable. Unlike HTML, a Markdown document still looks like a document when you open the raw file. Unlike a word processor format, it is plain text: small, portable, easy to search, and friendly to version control.

How Markdown works

A Markdown workflow has two layers:

1. Source: the plain-text characters stored in a .md or .markdown file.
2. Rendered output: the styled headings, paragraphs, links, and other elements shown by an app or converted to HTML, PDF, or another format.

For example, the source below is useful even before it is rendered:

# Release checklist

Before publishing:

- [x] Review the copy
- [ ] Test every link
- [ ] Export the final PDF

Read the [project guide](https://example.com/guide).

Markdown was created by John Gruber in 2004 with readability as its central design goal. Today it is used for README files, technical documentation, notes, static websites, forum posts, and messages in many collaboration tools.

What is a Markdown file?

A Markdown file is a UTF-8 plain-text file, usually ending in .md. The extension tells compatible apps to interpret Markdown punctuation as formatting instructions. The file itself contains no hidden layout data.

You can open an .md file in Notepad, but a dedicated editor is more comfortable because it adds syntax highlighting, shortcuts, an outline, and a rendered preview. Hashdraft keeps both views together: edit the source, read the result, or work with both side by side.

Markdown syntax cheat sheet

The following core syntax works in most Markdown implementations. Keep a blank line between paragraphs and around block elements when in doubt. For a searchable, copyable version, open the interactive Markdown cheat sheet.

Headings

Put one to six hash characters before the heading text. One # creates the document title; ## starts a major section; deeper levels create subsections.

# Document title
## Main section
### Subsection

Use heading levels in order. A logical hierarchy helps readers scan the page and gives screen readers and search engines a clearer document outline.

Bold and italic text

Use **bold** for strong importance.
Use *italic* for emphasis.
Use ***both*** when the distinction is genuinely useful.

Asterisks are generally the most portable choice. Underscores also work in many parsers, but can behave unexpectedly inside words.

Lists and task lists

- First bullet
- Second bullet
  - Nested bullet

1. First step
2. Second step

- [x] Completed task
- [ ] Open task

Basic bullet and numbered lists are part of core Markdown. Checkboxes are a common extension supported by GitHub Flavored Markdown and many editors, including Hashdraft.

Quotes and code

Start a paragraph with > for a blockquote. Wrap a short command or identifier in one backtick. For several lines of code, use three backticks before and after the block; add a language name after the opening fence for syntax highlighting.

> Good documentation answers the next question.

Run `npm test` before committing.

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

Markdown URL and link syntax

A Markdown URL is simply the destination inside a Markdown link. The most common form is an inline link: put the human-readable label in square brackets and the destination URL in parentheses.

[Read the Hashdraft guide](https://necromind.github.io/hashdraft/)

Use descriptive link text. “Read the Hashdraft guide” tells a reader where the link goes; “click here” does not. Clear labels also improve accessibility.

Absolute, relative, and anchor URLs

Relative links are usually best inside a repository or documentation folder because they continue to work when the whole folder moves. Heading-anchor rules vary slightly by renderer, so test internal links in the platform where the document will be published.

URLs with spaces or parentheses

A URL cannot contain a literal space. Encode it as %20, or—where the parser supports it—put the destination between angle brackets. Balanced parentheses are accepted by CommonMark, but encoding unusual characters produces more portable links.

[Quarterly report](reports/Q2%20report.pdf)
[Search](https://example.com/search?q=markdown&sort=new)

Reference-style links

Reference links keep long URLs out of a busy paragraph. Write a label in the text and define its destination elsewhere in the document:

Read the [CommonMark specification][spec] for edge cases.

[spec]: https://spec.commonmark.org/current/ "CommonMark specification"

Inline and reference links render the same way. Use inline links when the source stays readable; use references when a URL repeats or interrupts the flow.

Images, tables, and other extensions

Image syntax is link syntax with an exclamation mark at the beginning:

![Hashdraft in Split mode](images/hashdraft-split.png)

The text in brackets is alternative text. Describe the image's useful content rather than its filename. Use a relative path for a local image and a full HTTPS URL for an externally hosted image.

Tables, task lists, strikethrough, footnotes, wiki links, and mathematical notation are widely supported extensions, but they are not all part of the original Markdown syntax. A GitHub-style table looks like this:

| Mode    | Best for                |
|---------|-------------------------|
| Edit    | Drafting source         |
| Preview | Reading the final page  |
| Split   | Revising source beside output |

Why Markdown can render differently

“Markdown” names a family of closely related syntaxes. The original rules established the idea, while later specifications and products resolved ambiguities or added features. The CommonMark vs GFM comparison explains the exact boundary.

• CommonMark defines a precise, heavily tested core syntax.
• GitHub Flavored Markdown (GFM) builds on CommonMark and adds tables, task-list items, strikethrough, and extended autolinks.
• Product-specific Markdown may add wiki links, callouts, front matter, math, diagrams, or custom directives.

If a document must work in several apps, stay close to CommonMark and test the few extensions you need. The most portable building blocks are headings, paragraphs, emphasis, links, images, blockquotes, lists, and code.

Create your first Markdown document

1. Create a plain-text file named notes.md.
2. Add one # heading, a short paragraph, and a list.
3. Add a descriptive link with [label](URL).
4. Open a preview and confirm the structure renders as expected.
5. Keep the source readable. If the punctuation becomes harder to understand than the content, simplify it.

Common Markdown mistakes

• Missing spaces after markers: write ## Heading, not ##Heading.
• Broken link punctuation: use square brackets for the label and parentheses for the destination.
• Local paths that only work on one computer: prefer project-relative paths over C:\Users\....
• Skipped heading levels: move from # to ##, not directly to ####.
• Depending on an unsupported extension: check whether the destination platform supports tables, footnotes, math, or wiki links.
• Using Markdown for precise page layout: Markdown describes structure, not exact typography. Style the renderer or use a controlled PDF export workflow when layout matters.

Frequently asked questions