Introduction:

If you have ever written a file called README.md, replied in a forum that renders fancy-looking text, or edited a note in a modern note-taking app, you have already met Markdown. Markdown is a lightweight markup language created by John Gruber in 2004, with considerable help from Aaron Swartz, for exactly one purpose: to let people format plain text without the distractions of buttons, toolbars and office-suite ribbons.

The genius of Markdown is that it is designed to be readable as-is. You write ## Welcome and you instantly understand it means a heading, even before any software renders it. Because the syntax is so small and so natural, the learning curve is gentle – most of the language fits on a single page.

Why Learn Markdown?:

Markdown has become the de facto plain-text formatting standard of the internet. GitHub, GitLab, Reddit, Discord, Notion, Obsidian, and most static-site generators all speak it. Once you know Markdown, none of these tools holds a secret over you. Here is why it is worth your time:

• Universally supported: The core syntax works in nearly every application, from code repositories to chat apps.
• Portable and future-proof: A .md file is plain text. It opens in any editor on any device, and it will still open in fifty years, with no software lock-in.
• Version-control friendly: Markdown is stored as readable lines, so tools like Git can show exactly what changed between two revisions.
• Fast to write: Your hands stay on the keyboard. No reaching for the mouse, no hunting through menus – **bold** is quicker than any toolbar click.
• Readable in its raw form: You can read, skim and review a Markdown file even before it is rendered.

Join the millions of developers, writers, and students who use Markdown every day. By the end of this guide, you will be able to format documents, contribute to open-source projects, and write clean notes – all in plain text.

The One Idea That Makes Markdown Easy:

Before diving into rules, understand the single idea behind the whole language: the punctuation you type is the formatting you get. The syntax characters were chosen to resemble what they mean. A number sign (#) at the start of a line looks like a heading. Asterisks (*) wrap words that should be emphasised. A greater-than sign (>) points at a quotation. A dash (-) starts a bullet. You are not memorising obscure codes; you are learning to read the structure of the text you are already writing.

Markdown is also forgiving. There is no compiler yelling at you, and no error messages. Start with a heading or two, add a list, and build up gradually. In fact, the best way to learn is to write a short document about something you enjoy using only the elements in the next section.

The Basic Syntax:

The basic syntax is the original set of elements from John Gruber’s design document, and nearly every Markdown application supports it. Learn these well, and you will feel at home almost anywhere Markdown is used.

Headings:

To create a heading, place number signs (#) at the start of a line. The number of signs sets the level – one sign for a top-level heading, up to six for the smallest one. Always leave a space between the signs and the heading text.

Notice how the rendered text grows smaller as the level increases. For a quick alternative, you can underline text with === for a level-1 heading or --- for a level-2 heading on the line below.

Paragraphs and Line Breaks:

A paragraph is simply a line (or a few consecutive lines) of text. Separate two paragraphs with a blank line so Markdown knows where one ends and the next begins.

To start a new line without starting a new paragraph, end the previous line with two or more spaces and then press Enter. This produces a hard line break – the same one you get from the HTML <br> tag. In the examples below there are two spaces after the word “bread” (shown here with underscores so you can see them):

Some writers prefer typing the <br> tag itself for line breaks, because trailing spaces are easy to miss. Both approaches work in most applications.

Bold, Italic and Bold-Italic:

Wrap text in two asterisks for bold, one asterisk for italic, and three for both at once. The table shows each one passing through HTML into the rendered result.

Underscores (__text__ and _text_) work the same way, but asterisks are the safer choice: in the middle of a word, underscores can be misread as ordinary characters, so writers and the guide recommend sticking with asterisks.

Blockquotes:

Prefix a line with a greater-than sign (>) to turn it into a quote.

Blank lines inside the quote need a > of their own to keep the quote alive, and a double >> nests a quote inside another one:

> The sea never gives up its maps.
>
> > All it offers are the tides, twice a day.

Lists:

Start lines with -, * or + for unordered (bullet) lists, and with a number followed by a period for ordered lists. Indent items by four spaces to create a nested list.

Ordered list items don’t need to be numbered in order – every line could say 1. and the list would still count correctly – but the list should start with 1. for reliable rendering. Stick to a single bullet style within one list, since mixing -, * and + can confuse some applications. To nest a list, indent the inner items by four spaces:

- Rowing oars
- Dry bags
  - Waterproof phone case
  - Spare gloves

Adding Elements in Lists:

To include a paragraph, a blockquote, code or an image inside a list item, indent that block by four spaces (or eight spaces inside a nested list) so it stays inside the item.

- Check the wind forecast.

    Offshore winds can build quickly in the afternoon.

- Pack a dry change of clothes.

Inline Code and Code Blocks:

Surround a word or phrase in backticks to mark it as code. If the code itself contains a backtick, wrap it in double backticks instead.

Type `knot -s` and press Enter to start the timer.

For a full block of code, the original Markdown indents every line by four spaces. Most modern applications also support fenced code blocks, which open and close with three backticks and need no indentation:

```
function greet(name) {
  return "Ahoy, " + name + "!";
}
```

Horizontal Rules:

Put three or more --- (dashes), *** (asterisks) or ___ (underscores) on a line by themselves to draw a horizontal divider. A blank line before and after keeps it from being read as something else.

---

Links:

Create a link by putting the link text in square brackets and following it immediately with the URL in parentheses. A title inside quotes after the URL shows as a tooltip on hover.

To turn a bare URL or email address into a link, wrap it in angle brackets:

<https://www.example.com/harbour>

Original Markdown also supports reference-style links, which store the URL once at the bottom of the file for easy reading:

See the [weather radar][radar].

[radar]: https://www.example.com/radar "Live coastal radar"

If a URL contains spaces, use %20 for each space, and %28 / %29 for parentheses, so the link is not cut short.

Images:

Images reuse the link syntax with a leading exclamation mark. The text in the brackets becomes the alt text; the parentheses hold the image source (and an optional title).

![Sunrise over Shell Point](images/sunrise.jpg "Morning at Shell Point")

To make an image a clickable link, wrap the whole image in the link syntax:

[![Sunrise over Shell Point](images/sunrise.jpg)](https://www.example.com/gallery)

Escaping Special Characters:

To show a character that Markdown would otherwise treat as formatting, put a backslash (\) in front of it.

\*This is a literal asterisk, not a bullet.*

You can escape the punctuation you have just learned. Here is the full list of escapable characters, exactly as the Markdown Guide’s reference presents it:

Raw HTML:

Markdown is not a replacement for HTML – it is a simpler way to write it, and raw HTML is allowed whenever you need more control. Use the <em> tag if you prefer it to asterisks, or a <span> to change colours:

This <em>word</em> is italic, and this word has <span>special styling</span>.

Separate block-level tags such as <div> or <table> from surrounding text with blank lines, and note that Markdown syntax inside those block-level tags is not converted – only inline HTML like <em> works there. Not every application allows raw HTML, so check your platform’s documentation.

Extended Syntax:

The basic syntax covers most everyday needs, but it does not include tables, task lists or footnotes. That is where extended syntax comes in. Several lightweight markup languages – CommonMark, GitHub Flavored Markdown (GFM), Markdown Extra, MultiMarkdown and R Markdown among them – add such elements on top of the basics.

Here is the important catch: not every application supports every extended element. GitHub, GitLab and most wiki tools handle most of them, but a bare-bones processor might not. When an element matters, check your application’s documentation – or try it. Below are the extended features you are most likely to meet.

Tables:

Build a table with pipes (|) separating columns and a row of dashes under the header. Add a colon to the left, right or both sides of the dashes to align text. For maximum compatibility, also put a pipe at the start and end of every row – some processors expect them.

| Trail       | Distance | Difficulty |
| :---------- | :------: | ---------: |
| Lakeview    |   3 km   |     Easy   |
| Summit Peak |   9 km   |    Hard    |

You can use links, code and emphasis inside cells, but not headings, lists or most HTML. To show a literal pipe inside a table cell, use its character code |.

Fenced Code Blocks with Syntax Highlighting:

Fenced code blocks let you skip the four-space indentation. Depending on the application you open them with three backticks or three tildes (~~~). Add a language name on the opening fence and many processors will colour-highlight the code.

```javascript
const tideTimes = ["06:12", "12:34", "18:47"];
```

Footnotes:

Add a reference marker [^1] in the text and define the note anywhere below the paragraph – identifiers can be numbers or words like [^lighthouse]. A footnote can hold several paragraphs when you indent them by four spaces, but it cannot sit inside another element such as a list, blockquote or table.

The oldest lighthouse here was built in 1876.[^1]

[^1]: Restoration work was completed in 2019.

Heading IDs:

Give a heading a custom identifier so you can link to it directly, either from the same page or from elsewhere.

### Tide Tables {#tide-tables}

You can then jump to that heading from anywhere in your document with a standard link whose URL is a number sign followed by the custom ID:

Other websites can point straight at the same heading by adding the custom ID to the full URL of the page, just as the example above does.

Definition Lists:

Write a term on one line and its definition on the next, starting with a colon and a space. Repeated colons give several definitions for one term.

Knot
: A measure of speed equal to one nautical mile per hour.

Riptide
: A strong narrow current flowing away from the shore.

Strikethrough:

Surround text with two tildes to strike it out. This is handy for marking something in a plan as no longer valid.

The picnic is ~~cancelled~~ moved indoors.

Task Lists:

Begin list items with - [ ] for an unchecked box or - [x] for a checked one to build a checklist.

- [x] Charge the headlamp
- [x] Pack the first-aid kit
- [ ] Top up the water jug

Emoji:

You can paste an emoji straight into a document, or, where supported, type a shortcode so it stays readable in the raw file.

Back on the trail by :sunrise: every morning.

That climb was a real achievement :clap:

Highlight, Subscript and Superscript:

A few processors let you mark text with ==two equals signs== for highlighting, wrap characters in a single tilde for subscript (H~2~O) and in carets for superscript (X^2^). Because these are uncommon, test them before relying on them – some applications use a single tilde for strikethrough instead. If your application supports HTML, the underlying tags – <mark>, <sub> and <sup> – are a safer fallback that works almost anywhere.

Automatic URL Linking:

Many processors turn a bare URL typed in the middle of a sentence into a clickable link with no brackets at all. To stop that, wrap the URL in backticks so it stays as plain code.

Visit https://www.example.com/harbour for live conditions.

`` `https://www.example.com/harbour` ``

Best Practices and Common Pitfalls:

Markdown applications do not always agree on edge cases. Follow these conventions and your documents will render correctly almost everywhere:

• Leave a space after the number signs: # Heading, never #Heading.
• Separate blocks with blank lines: put blank lines before and after headings, blockquotes and horizontal rules so they are not merged into surrounding text.
• Prefer asterisks for emphasis: underscores can fail in the middle of a word, e.g. Very**very**good.
• Do not mix bullet markers in one list: pick -, * or + and keep it.
• Start ordered lists at 1: the numbers themselves can be any order afterwards.
• Do not indent paragraphs with tabs or spaces – an indented line may be read as a code block.
• Encode problem characters in URLs: spaces become %20; parentheses become %28 and %29.
• Pick one line-break style: two trailing spaces, or the <br> tag, but not a bare newline when you need a real break.
• Check extended syntax support in your application before producing tables, task lists or footnotes for a large document.

Some of those rules are easiest to remember side by side – what to do and what to avoid:

Put Markdown to Work:

Now that you know the syntax, the fastest way to build confidence is to use Markdown where you already write:

• README files and issues on GitHub – format project descriptions, checklists and references with the habits you just learned.
• Notes and knowledge bases – Obsidian, Notion and others accept Markdown, so your notes stay portable even if you switch apps.
• Forums and chat – many communities render **bold**, _italics_ and fenced code automatically.
• Documentation and blogs – static-site generators such as Jekyll, Hugo and Eleventy publish .md files directly.
• Migrating existing content – if you already have HTML pages or articles and want them in Markdown, use the free HTML to Markdown Converter here at Text-Toolz. Paste the HTML, press Convert, and you get clean Markdown in seconds. It is a great way to see how real-world markup translates to the syntax you have just learned.
• Publishing Markdown to the web – when you have a .md file and need web-ready markup, the free Markdown to HTML Converter here at Text-Toolz turns it into a paste-ready HTML fragment in seconds, so you can put your notes online without retyping them.

Write a short page about your current hobby in Markdown today. Half an hour of practice with headings, lists, emphasis and links is all it takes for the syntax to stick.

Markdown Cheat Sheet:

Keep this reference handy. It summarises the elements covered in this guide – first the basic syntax, then the most common extended additions. Every example above is built from these blocks.

Basic Syntax:

Extended Syntax:

Conclusion:

Markdown is one of the few skills that pays off the moment you learn it. It is small, it is everywhere, and it never locks your writing inside a single product. Start with the basic syntax – headings, paragraphs, emphasis, lists, links and code – and reach for the extended elements whenever a platform supports them.

Print the cheat sheet above, write a few short documents, and before long the syntax will feel like second nature. And when you meet a web page you would love to have in Markdown form, the HTML to Markdown Converter on this site is always ready to help you turn it into clean, portable text.