Basic

About 3434 wordsAbout 11 min

Guidemarkdown

2025-03-03

This document is forked from vuepress-theme-hope, following the MIT license.

Markdown is a markup language that can be written using a plain text editor. Through simple syntax, it allows regular text content to have formatting capabilities.

The goal of Markdown is to achieve「readability and writability」.

Overview

The most emphasized aspect is its readability. A document written in Markdown should be directly publishable as plain text, and should not appear to be composed of tags or formatting instructions. Markdown syntax is influenced by several existing text-to-HTML formats, including Setext, atx, Textile, reStructuredText, Grutatxt, and EtText, with the primary inspiration coming from plain text email formatting.

Thus, Markdown syntax consists entirely of punctuation marks, carefully selected to visually represent their meaning. For example, adding asterisks around text looks like *emphasis*. Markdown lists look like lists. If you've used email, blockquotes resemble quoted text.

Markdown has various derivatives to extend its functionality (e.g., tables, footnotes, embedded HTML), features not originally available in basic Markdown. These enable conversion to formats like LaTeX, Docbook. Notable enhanced versions include Markdown Extra, MultiMarkdown, and Maruku. These derivatives are either tool-based (e.g., Pandoc) or website-based (e.g., GitHub, Wikipedia), maintaining basic syntax compatibility but modifying rendering effects.

Usage

Markdown's syntax has a primary purpose: to serve as a writing language for web content. Markdown focuses on making documents easier to read and write, thus its syntax only covers what plain text can represent.

Markdown's syntax is simple, easy to learn, and more powerful than plain text, making it popular for blogging. WordPress, the world's most popular blogging platform, supports Markdown well.

It's used for documentation, typically saved as README.md in software directories.

Additionally, Markdown can quickly convert to presentation slides, Word documents, LaTeX papers, or even minimal viable prototypes with minimal code. In data science, Markdown has become essential for dynamic reproducible research.

Inline HTML

Any HTML tags not covered by Markdown can be directly written in the document. No special annotation is needed; simply include the tags.

Block-level elements like <div>, <table>, <pre>, and  must be separated by blank lines. These tags cannot be indented with tabs or spaces. Markdown's parser intelligently avoids adding unnecessary  tags around block elements.

For example, adding an HTML table in a Markdown file:

This is a regular paragraph.

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

This is another regular paragraph.

Note that Markdown syntax is not processed within HTML blocks. For instance, you cannot use *emphasis* inside HTML blocks.

Special Character Auto-Conversion

In HTML files, two characters require special handling: < and &. The < character starts a tag, and & marks an HTML entity. If you want to use these characters literally, you must use their entity forms, like < and &.

The & character can be problematic for those writing web documents. If you want to write "AT&T," you must write "AT&T." You also need to escape the & in URLs. For example, if you want to link to http://images.google.com/images?num=30&q=larry+bird

you must convert the URL to:

http://images.google.com/images?num=30&amp;q=larry+bird

to place it in the href attribute of a link tag. It's easy to forget this, and it might be the most common error detected by HTML validators.

Markdown allows you to use these characters directly, but you need to be careful with escape characters. If you use & in an HTML entity, it won't be converted. In other cases, it will be converted to &. So, if you want to insert a copyright symbol in your text, you can write:

&copy;

Markdown will not modify this text. However, if you write:

AT&T

Markdown will convert it to:

AT&amp;T

Similar behavior occurs with the < character. Since Markdown supports inline HTML, if you use < as an HTML tag, Markdown won't convert it. But if you write:

4 < 5

Markdown will convert it to:

4 &lt; 5

Note that within code spans, whether inline or block, both < and & are always converted to HTML entities. This feature allows you to easily write HTML code in Markdown, as you don't have to convert all < and & in HTML syntax to HTML entities to write HTML code.

Block Elements

Paragraphs and Line Breaks

A paragraph is composed of one or more connected lines, and one or more blank lines separate different paragraphs. (A blank line is defined as a line that appears empty; for example, a line with only spaces and tabs is also considered a blank line.) Generally, paragraphs do not require indentation with spaces or tabs.

The phrase "composed of one or more connected lines" implies that Markdown allows forced line breaks within paragraphs. This differs from other text-to-HTML formats (including MovableType's "Convert Line Breaks" option), which convert every line break into a   tag.

If you really want to insert a   tag, add two or more spaces () or a slash (/) at the end of the line, then press Enter.

Yes, this requires more effort to insert a  , but the method of converting every line break to   is not suitable for Markdown. In Markdown, email-style block quotes and multi-paragraph lists are more usable and readable when using line breaks for formatting.

Headings

Headings indicate the structure of an article.

Markdown supports two heading syntax styles: Setext and atx.

The Setext style uses underlines with = (for first-level headings) and - (for second-level headings), like:

# This is an H1

## This is an H2

Any number of = or - characters can be used.

The Atx style (recommended) involves placing 1 to 6 # characters at the beginning of a line, corresponding to heading levels 1 to 6, like:

H1: # Header 1
H2: ## Header 2
H3: ### Header 3
H4: #### Header 4
H5: ##### Header 5
H6: ###### Header 6

Blockquotes

Markdown uses email-style block quotes. If you're familiar with quoting in emails, you'll know how to create a block quote in a Markdown file. It looks like a forced line break with > at the beginning of each line:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

Markdown also allows you to place > only at the beginning of the first line of a paragraph:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

Block quotes can have levels (e.g., quotes within quotes) by adding more > characters according to the level:

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

Other Markdown syntax, including headings, lists, and code blocks, can be used within block quotes:

> ## This is a header.
>
> 1. This is the first list item.
> 1. This is the second list item.
>
> Here's some example code:
>
>     return shell_exec("echo $input | $markdown_script");

Any standard text editor can easily create email-style quotes. For example, in BBEdit, you can select text and choose "Increase Quote Level" from the menu.

Lists

Markdown supports ordered and unordered lists.

Unordered lists use hyphens as list markers (you can also use asterisks or plus signs):

- Red
- Green
- Blue

You can also (though not recommended):

- Red
- Green
- Blue

* Red
* Green
* Blue

Ordered lists use numbers followed by a period:

1. Bird
2. McHale
3. Parish

Importantly, the numbers you use for list markers do not affect the HTML output. The HTML for the above list would be:

<ol>
  <li>Bird</li>
  <li>McHale</li>
  <li>Parish</li>
</ol>

If you write the list markers as:

1. Bird
1. McHale
1. Parish

You'll still get the same HTML output. The key point is that you can make the list numbers in the Markdown file match the output, or just use 1 and not worry about the numbering.

List markers are typically placed at the left margin but can be indented by up to three spaces, with at least one space or tab after the marker.

To make lists look neater, you can align the content with consistent indentation:

- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
  viverra nec, fringilla in, laoreet vitae, risus.
- Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
  Suspendisse id sem consectetuer libero luctus adipiscing.

However, if you're lazy, you don't have to:

- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
  viverra nec, fringilla in, laoreet vitae, risus.
- Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
  Suspendisse id sem consectetuer libero luctus adipiscing.

If list items are separated by blank lines, Markdown will wrap the item content in  tags. For example:

- Bird
- Magic

Would be converted to:

<ul>
  <li>Bird</li>
  <li>Magic</li>
</ul>

But this:

- Bird

- Magic

Would be converted to:

<ul>
  <li><p>Bird</p></li>
  <li><p>Magic</p></li>
</ul>

List items can contain multiple paragraphs, with each paragraph indented by 4 spaces or one tab:

1. This is a list item with two paragraphs. Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.

2. Suspendisse id sem consectetuer libero luctus adipiscing.

If every line is indented, it looks better, but again, if you're lazy, Markdown allows:

- This is a list item with two paragraphs.

  This is the second paragraph in the list item. You're
  only required to indent the first line. Lorem ipsum dolor
  sit amet, consectetuer adipiscing elit.

- Another item in the same list.

To include a quote within a list item, the > needs to be indented:

- A list item with a blockquote:

  > This is a blockquote
  > inside a list item.

Accidental lists can occur with syntax like:

1986. What a great season.

To avoid this, place a backslash before the period:

1986\. What a great season.

Code Blocks

For code writing or raw code of markup languages, you often need preformatted code blocks that shouldn't be formatted like regular paragraphs but displayed as-is. Markdown wraps these code blocks with <pre> and <code> tags.

Creating a code block in Markdown is simple: indent every line with 4 spaces or one tab. For example:

This is a normal paragraph:

This is a code block.

Markdown converts this to:

<p>This is a normal paragraph:</p>

<pre>
  <code>This is a code block.</code>
</pre>

The indentation (4 spaces or one tab) is removed, so:

Here is an example of AppleScript:

tell application "Foo"
beep
end tell

Becomes:

<p>Here is an example of AppleScript:</p>

<pre><code>tell application "Foo"
  beep
end tell
</code></pre>

A code block continues until a line with no indentation (or the end of the file).

Within code blocks, <, &, and > are automatically converted to HTML entities, making it easy to insert HTML code examples. Just copy, paste, and indent, and Markdown handles the rest. For example:

```html
<div class="footer">
  &copy; 2004 Foo Corporation
</div>
```

Is converted to:

<pre>
  <code>&lt;div class="footer"&gt;
  &amp;copy; 2004 Foo Corporation
&lt;/div&gt;</code>
</pre>

In code blocks, regular Markdown syntax isn't processed, so asterisks remain asterisks. This allows you to easily write about Markdown syntax.

If you want to include Markdown-formatted code libraries within a code block, you can nest them.

````md
```js
const a = 1
```
````

Renders as

```js
const a = 1
```

Horizontal Rules

You can create a horizontal rule by placing three or more asterisks, hyphens, or underscores on a line. No other content should be on the line. You can also add spaces between the characters. Any of the following will create a horizontal rule:

---(recommended) * * * *** ***** - - - ---------------------------------------

Inline Elements

Links

Markdown supports two types of link syntax: inline and reference.

In both cases, link text is marked with [square brackets].

For an inline link, immediately after the square brackets, add parentheses with the URL. You can also include a title in quotes, like:

This is [an example](http://example.com/  "Title") inline link. [This
link](http://example.net/  ) has no title attribute.

This produces:

<p>
  This is <a href="http://example.com/  " title="Title"> an example</a> inline
  link.
</p>

<p><a href="http://example.net/  ">This link</a> has no title attribute.</p>

For linking to resources on the same host, you can use relative paths:

See my [About](/about/) page for details.

Reference-style links use another set of square brackets after the link text, with an identifier for the link:

This is [an example][id] reference-style link.

Then, define the link identifier anywhere in the document:

[id]: http://example.com/  "Optional Title Here"

The link definition consists of:

Square brackets with the link ID
A colon
One or more spaces or a tab
The URL
An optional title in single quotes, double quotes, or parentheses

These three link definitions are equivalent:

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  "Optional Title Here"

Note: A known issue is that Markdown.pl 1.0.1 ignores single-quoted link titles.

URLs in link definitions can be enclosed in square brackets:

[id]: http://example.com/  "Optional Title Here"

You can also place the title on a new line with indentation for better readability with long URLs:

[id]: http://example.com/longish/path/to/resource/here  "Optional Title Here"

Link identifiers are case-insensitive and can include letters, numbers, spaces, and punctuation. These two links are the same:

[link text][a]
[link text][a]

The default link ID feature allows you to omit the link ID, making it the same as the link text. To use this, add empty square brackets after the link text. For example:

[Google][]

Then define the link:

[google]: http://google.com/

Since link text can contain spaces, the simplified ID can also include multiple words:

Visit [Daring Fireball][] for more information.

Then define the link:

[daring fireball]: http://daringfireball.net/

Link definitions can be placed anywhere in the document, either after the paragraph where the link appears or at the end like annotations.

Here's an example of reference-style links:

I get 10 times more traffic from [Google][1] than from
[Yahoo][2] or [MSN][3].

[1]: http://google.com/  "Google"
[2]: http://search.yahoo.com/  "Yahoo Search"
[3]: http://search.msn.com/  "MSN Search"

Using link names instead:

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

[google]: http://google.com/  "Google"
[yahoo]: http://search.yahoo.com/  "Yahoo Search"
[msn]: http://search.msn.com/  "MSN Search"

Both methods produce the same HTML:

<p>
  I get 10 times more traffic from
  <a href="http://google.com/  " title="Google">Google</a> than from
  <a href="http://search.yahoo.com/  " title="Yahoo Search">Yahoo</a>
  or <a href="http://search.msn.com/  " title="MSN Search">MSN</a>.
</p>

For comparison, here's the inline-style version of the same content:

I get 10 times more traffic from [Google](http://google.com/  "Google")
than from [Yahoo](http://search.yahoo.com/  "Yahoo Search") or
[MSN](http://search.msn.com/  "MSN Search").

Reference-style links are more readable. The reference-style version has 81 characters, while the inline-style version has 176, and pure HTML would have 234. In HTML, tags outnumber text.

Using Markdown's reference-style links makes the document resemble the final browser output, allowing you to keep markup details separate from the main text for uninterrupted reading.

Emphasis

Markdown uses asterisks (*) and underscores (_) to mark emphasis. Text surrounded by * or _ is wrapped in , while text surrounded by double * or _ is wrapped in , like:

**double asterisks** (recommended)

**double underscores** (recommended)

_single asterisks_

_single underscores_

This converts to:

<em>single asterisks</em>

<em>single underscores</em>

<strong>double asterisks</strong>

<strong>double underscores</strong>

You can choose your preferred style, as long as you use the same character to open and close.

Emphasis can be added in the middle of words:

un*frigging*believable

However, if * or _ has spaces on both sides, it will be treated as regular text.

To insert literal asterisks or underscores, use a backslash:

\*this text is surrounded by literal asterisks\*

Code

To mark inline code, wrap it in backticks (`), like:

Use the `printf()` function.

This produces:

<p>Use the <code>printf()</code> function.</p>

To include a backtick within the code, use multiple backticks to open and close the inline code:

``There is a literal backtick (`) here.``

This renders as:

<p><code>There is a literal backtick (`) here.</code></p>

You can add a space at the start or end of the code span to include a backtick at the beginning:

A single backtick in a code span: `` ` ``

A backtick-delimited string in a code span: `` `foo` ``

This results in:

<p>A single backtick in a code span: <code>`</code></p>

<p>A backtick-delimited string in a code span: <code>`foo`</code></p>

Within code spans, & and brackets are converted to HTML entities, making it easier to insert HTML code. Markdown converts:

Please don't use any `<blink>` tags.

To:

<p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>

You can also write:

`&#8212;` is the decimal-encoded equivalent of `&mdash;`.

Which produces:

<p>
  <code>&amp;#8212;</code> is the decimal-encoded equivalent of
  <code>&amp;mdash;</code>.
</p>

Images

Creating a natural syntax for inserting images in plain text is challenging.

Markdown uses a syntax similar to links for images, supporting both inline and reference styles.

The inline image syntax looks like:

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

This consists of:

An exclamation mark !
Square brackets containing the image's alt text
Parentheses containing the image URL, optionally followed by a quoted title.

Reference-style image syntax looks like:

![Alt text][id]

Where id is the image reference name, defined like:

[id]: url/to/image "Optional title attribute"

Currently, Markdown doesn't support specifying image width and height. For that, use the regular <img> tag.

Other Text Styles

Delete: ~~delete~~
Paragraphs: Leave a blank line between paragraphs
Line breaks: Add two spaces at the end of a line

Other

Automatic Links

Markdown supports concise automatic link syntax for URLs and email addresses. Enclosing text in brackets automatically converts it to a link. For example:

<http://example.com/>

Markdown converts this to:

<a href="http://example.com/">http://example.com/</a>

Automatic email links are similar, but Markdown encodes characters as hexadecimal HTML entities to confuse address-harvesting bots. For example:

<address@example.com>

Markdown converts this to:

<a
  href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;"
  >&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a
>

This creates a clickable address@example.com link in the browser.

Escape Characters

Markdown uses backslashes to insert characters that have special meaning in its syntax. For example, to use asterisks for emphasis without  tags, precede them with a backslash: