|
| 1 | +--- |
| 2 | +link: md |
| 3 | +description: Overview of Markdown syntax. |
| 4 | +--- |
| 5 | + |
| 6 | +# Markdown: Syntax |
| 7 | + |
| 8 | +* [Overview](#overview) |
| 9 | + * [Philosophy](#philosophy) |
| 10 | + * [Inline HTML](#html) |
| 11 | + * [Automatic Escaping for Special Characters](#autoescape) |
| 12 | +* [Block Elements](#block) |
| 13 | + * [Paragraphs and Line Breaks](#p) |
| 14 | + * [Headers](#header) |
| 15 | + * [Blockquotes](#blockquote) |
| 16 | + * [Lists](#list) |
| 17 | + * [Code Blocks](#precode) |
| 18 | + * [Horizontal Rules](#hr) |
| 19 | +* [Span Elements](#span) |
| 20 | + * [Links](#link) |
| 21 | + * [Emphasis](#em) |
| 22 | + * [Code](#code) |
| 23 | + * [Images](#img) |
| 24 | +* [Miscellaneous](#misc) |
| 25 | + * [Backslash Escapes](#backslash) |
| 26 | + * [Automatic Links](#autolink) |
| 27 | + |
| 28 | + |
| 29 | +**Note:** This document is itself written using Markdown; you |
| 30 | +can [see the source for it by adding '.text' to the URL](/projects/markdown/syntax.text). |
| 31 | + |
| 32 | +---- |
| 33 | + |
| 34 | +## Overview |
| 35 | + |
| 36 | +### Philosophy |
| 37 | + |
| 38 | +Markdown is intended to be as easy-to-read and easy-to-write as is feasible. |
| 39 | + |
| 40 | +Readability, however, is emphasized above all else. A Markdown-formatted |
| 41 | +document should be publishable as-is, as plain text, without looking |
| 42 | +like it's been marked up with tags or formatting instructions. While |
| 43 | +Markdown's syntax has been influenced by several existing text-to-HTML |
| 44 | +filters -- including [Setext](http://docutils.sourceforge.net/mirror/setext.html), [atx](http://www.aaronsw.com/2002/atx/), [Textile](http://textism.com/tools/textile/), [reStructuredText](http://docutils.sourceforge.net/rst.html), |
| 45 | +[Grutatext](http://www.triptico.com/software/grutatxt.html), and [EtText](http://ettext.taint.org/doc/) -- the single biggest source of |
| 46 | +inspiration for Markdown's syntax is the format of plain text email. |
| 47 | + |
| 48 | +## Block Elements |
| 49 | + |
| 50 | +### Paragraphs and Line Breaks |
| 51 | + |
| 52 | +A paragraph is simply one or more consecutive lines of text, separated |
| 53 | +by one or more blank lines. (A blank line is any line that looks like a |
| 54 | +blank line -- a line containing nothing but spaces or tabs is considered |
| 55 | +blank.) Normal paragraphs should not be indented with spaces or tabs. |
| 56 | + |
| 57 | +The implication of the "one or more consecutive lines of text" rule is |
| 58 | +that Markdown supports "hard-wrapped" text paragraphs. This differs |
| 59 | +significantly from most other text-to-HTML formatters (including Movable |
| 60 | +Type's "Convert Line Breaks" option) which translate every line break |
| 61 | +character in a paragraph into a `<br />` tag. |
| 62 | + |
| 63 | +When you *do* want to insert a `<br />` break tag using Markdown, you |
| 64 | +end a line with two or more spaces, then type return. |
| 65 | + |
| 66 | +### Headers |
| 67 | + |
| 68 | +Markdown supports two styles of headers, [Setext] [1] and [atx] [2]. |
| 69 | + |
| 70 | +Optionally, you may "close" atx-style headers. This is purely |
| 71 | +cosmetic -- you can use this if you think it looks better. The |
| 72 | +closing hashes don't even need to match the number of hashes |
| 73 | +used to open the header. (The number of opening hashes |
| 74 | +determines the header level.) |
| 75 | + |
| 76 | + |
| 77 | +### Blockquotes |
| 78 | + |
| 79 | +Markdown uses email-style `>` characters for blockquoting. If you're |
| 80 | +familiar with quoting passages of text in an email message, then you |
| 81 | +know how to create a blockquote in Markdown. It looks best if you hard |
| 82 | +wrap the text and put a `>` before every line: |
| 83 | + |
| 84 | +> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, |
| 85 | +> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. |
| 86 | +> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. |
| 87 | +> |
| 88 | +> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse |
| 89 | +> id sem consectetuer libero luctus adipiscing. |
| 90 | +
|
| 91 | +Markdown allows you to be lazy and only put the `>` before the first |
| 92 | +line of a hard-wrapped paragraph: |
| 93 | + |
| 94 | +> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, |
| 95 | +consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. |
| 96 | +Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. |
| 97 | + |
| 98 | +> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse |
| 99 | +id sem consectetuer libero luctus adipiscing. |
| 100 | + |
| 101 | +Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by |
| 102 | +adding additional levels of `>`: |
| 103 | + |
| 104 | +> This is the first level of quoting. |
| 105 | +> |
| 106 | +> > This is nested blockquote. |
| 107 | +> |
| 108 | +> Back to the first level. |
| 109 | +
|
| 110 | +Blockquotes can contain other Markdown elements, including headers, lists, |
| 111 | +and code blocks: |
| 112 | + |
| 113 | +> ## This is a header. |
| 114 | +> |
| 115 | +> 1. This is the first list item. |
| 116 | +> 2. This is the second list item. |
| 117 | +> |
| 118 | +> Here's some example code: |
| 119 | +> |
| 120 | +> return shell_exec("echo $input | $markdown_script"); |
| 121 | +
|
| 122 | +Any decent text editor should make email-style quoting easy. For |
| 123 | +example, with BBEdit, you can make a selection and choose Increase |
| 124 | +Quote Level from the Text menu. |
| 125 | + |
| 126 | + |
| 127 | +### Lists |
| 128 | + |
| 129 | +Markdown supports ordered (numbered) and unordered (bulleted) lists. |
| 130 | + |
| 131 | +Unordered lists use asterisks, pluses, and hyphens -- interchangably |
| 132 | +-- as list markers: |
| 133 | + |
| 134 | +* Red |
| 135 | +* Green |
| 136 | +* Blue |
| 137 | + |
| 138 | +is equivalent to: |
| 139 | + |
| 140 | ++ Red |
| 141 | ++ Green |
| 142 | ++ Blue |
| 143 | + |
| 144 | +and: |
| 145 | + |
| 146 | +- Red |
| 147 | +- Green |
| 148 | +- Blue |
| 149 | + |
| 150 | +Ordered lists use numbers followed by periods: |
| 151 | + |
| 152 | +1. Bird |
| 153 | +2. McHale |
| 154 | +3. Parish |
| 155 | + |
| 156 | +It's important to note that the actual numbers you use to mark the |
| 157 | +list have no effect on the HTML output Markdown produces. The HTML |
| 158 | +Markdown produces from the above list is: |
| 159 | + |
| 160 | +If you instead wrote the list in Markdown like this: |
| 161 | + |
| 162 | +1. Bird |
| 163 | +1. McHale |
| 164 | +1. Parish |
| 165 | + |
| 166 | +or even: |
| 167 | + |
| 168 | +3. Bird |
| 169 | +1. McHale |
| 170 | +8. Parish |
| 171 | + |
| 172 | +you'd get the exact same HTML output. The point is, if you want to, |
| 173 | +you can use ordinal numbers in your ordered Markdown lists, so that |
| 174 | +the numbers in your source match the numbers in your published HTML. |
| 175 | +But if you want to be lazy, you don't have to. |
| 176 | + |
| 177 | +To make lists look nice, you can wrap items with hanging indents: |
| 178 | + |
| 179 | +* Lorem ipsum dolor sit amet, consectetuer adipiscing elit. |
| 180 | + Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, |
| 181 | + viverra nec, fringilla in, laoreet vitae, risus. |
| 182 | +* Donec sit amet nisl. Aliquam semper ipsum sit amet velit. |
| 183 | + Suspendisse id sem consectetuer libero luctus adipiscing. |
| 184 | + |
| 185 | +But if you want to be lazy, you don't have to: |
| 186 | + |
| 187 | +* Lorem ipsum dolor sit amet, consectetuer adipiscing elit. |
| 188 | +Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, |
| 189 | +viverra nec, fringilla in, laoreet vitae, risus. |
| 190 | +* Donec sit amet nisl. Aliquam semper ipsum sit amet velit. |
| 191 | +Suspendisse id sem consectetuer libero luctus adipiscing. |
| 192 | + |
| 193 | +List items may consist of multiple paragraphs. Each subsequent |
| 194 | +paragraph in a list item must be indented by either 4 spaces |
| 195 | +or one tab: |
| 196 | + |
| 197 | +1. This is a list item with two paragraphs. Lorem ipsum dolor |
| 198 | + sit amet, consectetuer adipiscing elit. Aliquam hendrerit |
| 199 | + mi posuere lectus. |
| 200 | + |
| 201 | + Vestibulum enim wisi, viverra nec, fringilla in, laoreet |
| 202 | + vitae, risus. Donec sit amet nisl. Aliquam semper ipsum |
| 203 | + sit amet velit. |
| 204 | + |
| 205 | +2. Suspendisse id sem consectetuer libero luctus adipiscing. |
| 206 | + |
| 207 | +It looks nice if you indent every line of the subsequent |
| 208 | +paragraphs, but here again, Markdown will allow you to be |
| 209 | +lazy: |
| 210 | + |
| 211 | +* This is a list item with two paragraphs. |
| 212 | + |
| 213 | + This is the second paragraph in the list item. You're |
| 214 | +only required to indent the first line. Lorem ipsum dolor |
| 215 | +sit amet, consectetuer adipiscing elit. |
| 216 | + |
| 217 | +* Another item in the same list. |
| 218 | + |
| 219 | +To put a blockquote within a list item, the blockquote's `>` |
| 220 | +delimiters need to be indented: |
| 221 | + |
| 222 | +* A list item with a blockquote: |
| 223 | + |
| 224 | + > This is a blockquote |
| 225 | + > inside a list item. |
| 226 | +
|
| 227 | +To put a code block within a list item, the code block needs |
| 228 | +to be indented *twice* -- 8 spaces or two tabs: |
| 229 | + |
| 230 | +* A list item with a code block: |
| 231 | + |
| 232 | + <code goes here> |
| 233 | + |
| 234 | +### Code Blocks |
| 235 | + |
| 236 | +Pre-formatted code blocks are used for writing about programming or |
| 237 | +markup source code. Rather than forming normal paragraphs, the lines |
| 238 | +of a code block are interpreted literally. Markdown wraps a code block |
| 239 | +in both `<pre>` and `<code>` tags. |
| 240 | + |
| 241 | +To produce a code block in Markdown, simply indent every line of the |
| 242 | +block by at least 4 spaces or 1 tab. |
| 243 | + |
| 244 | +This is a normal paragraph: |
| 245 | + |
| 246 | + This is a code block. |
| 247 | + |
| 248 | +Here is an example of AppleScript: |
| 249 | + |
| 250 | + tell application "Foo" |
| 251 | + beep |
| 252 | + end tell |
| 253 | + |
| 254 | +A code block continues until it reaches a line that is not indented |
| 255 | + |
| 256 | +(or the end of the article). |
| 257 | + |
| 258 | +Within a code block, ampersands (`&`) and angle brackets (`<` and `>`) |
| 259 | +are automatically converted into HTML entities. This makes it very |
| 260 | +easy to include example HTML source code using Markdown -- just paste |
| 261 | +it and indent it, and Markdown will handle the hassle of encoding the |
| 262 | +ampersands and angle brackets. For example, this: |
| 263 | + |
| 264 | + <div class="footer"> |
| 265 | + © 2004 Foo Corporation |
| 266 | + </div> |
| 267 | + |
| 268 | +Regular Markdown syntax is not processed within code blocks. E.g., |
| 269 | +asterisks are just literal asterisks within a code block. This means |
| 270 | +it's also easy to use Markdown to write about Markdown's own syntax. |
| 271 | + |
| 272 | +``` |
| 273 | +tell application "Foo" |
| 274 | + beep |
| 275 | +end tell |
| 276 | +``` |
| 277 | + |
| 278 | +## Span Elements |
| 279 | + |
| 280 | +### Links |
| 281 | + |
| 282 | +Markdown supports two style of links: *inline* and *reference*. |
| 283 | + |
| 284 | +In both styles, the link text is delimited by [square brackets]. |
| 285 | + |
| 286 | +To create an inline link, use a set of regular parentheses immediately |
| 287 | +after the link text's closing square bracket. Inside the parentheses, |
| 288 | +put the URL where you want the link to point, along with an *optional* |
| 289 | +title for the link, surrounded in quotes. For example: |
| 290 | + |
| 291 | +This is [an example](http://example.com/) inline link. |
| 292 | + |
| 293 | +[This link](http://example.net/) has no title attribute. |
| 294 | + |
| 295 | +### Emphasis |
| 296 | + |
| 297 | +Markdown treats asterisks (`*`) and underscores (`_`) as indicators of |
| 298 | +emphasis. Text wrapped with one `*` or `_` will be wrapped with an |
| 299 | +HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML |
| 300 | +`<strong>` tag. E.g., this input: |
| 301 | + |
| 302 | +*single asterisks* |
| 303 | + |
| 304 | +_single underscores_ |
| 305 | + |
| 306 | +**double asterisks** |
| 307 | + |
| 308 | +__double underscores__ |
| 309 | + |
| 310 | +### Code |
| 311 | + |
| 312 | +To indicate a span of code, wrap it with backtick quotes (`` ` ``). |
| 313 | +Unlike a pre-formatted code block, a code span indicates code within a |
| 314 | +normal paragraph. For example: |
| 315 | + |
| 316 | +Use the `printf()` function. |
0 commit comments