{"id":9128,"date":"2013-02-27T12:06:21","date_gmt":"2013-02-27T17:06:21","guid":{"rendered":"https:\/\/crashingpatient.com\/?p=9128"},"modified":"2014-07-15T18:14:15","modified_gmt":"2014-07-15T22:14:15","slug":"markdown-syntax-from-bret-terpstra","status":"publish","type":"post","link":"https:\/\/crashingpatient.com\/miscellaneous\/markdown-syntax-from-bret-terpstra.htm\/","title":{"rendered":"Markdown Syntax from John Gruber’s Site"},"content":{"rendered":"

<\/span>Markdown Syntax<\/span><\/h2>\n

<\/span>from Daring Fireball: Markdown Syntax Documentation<\/a><\/span><\/h3>\n

<\/span>Inline HTML<\/span><\/h3>\n

For any markup that is not covered by Markdown\u2019s syntax, you simply use HTML itself. There\u2019s no need to preface it or delimit it to indicate that you\u2019re switching from Markdown to HTML; you just use the tags. The only restrictions are that block-level HTML elements \u2014 e.g. <div><\/code>, <table><\/code>, <pre><\/code>, <p><\/code>, etc. \u2014 must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. Markdown is smart enough not to add extra (unwanted) <p><\/code> tags around HTML block-level tags. For example, to add an HTML table to a Markdown article: <\/p>\n

This is a regular paragraph. <table> <tr> <td>Foo<\/td> <\/tr> <\/table> This is another regular paragraph. <\/code><\/pre>\n
 Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can\u2019t use Markdown-style *emphasis*<\/code> inside an HTML block. Span-level HTML tags \u2014 e.g. <span><\/code>, <cite><\/code>, or <del><\/code> \u2014 can be used anywhere in a Markdown paragraph, list item, or header. If you want, you can even use HTML tags instead of Markdown formatting; e.g. if you\u2019d prefer to use HTML <a><\/code> or <img><\/code> tags instead of Markdown\u2019s link or image syntax, go right ahead. Unlike block-level HTML tags, Markdown syntax is<\/em> processed within span-level tags. <\/p>\n
<\/span>Automatic Escaping for Special Characters<\/span><\/h3>\n
 Markdown allows you to use these characters naturally, taking care of all the necessary escaping for you. If you use an ampersand as part of an HTML entity, it remains unchanged; otherwise it will be translated into &amp;<\/code>. So, if you want to include a copyright symbol in your article, you can write: <\/p>\n
&copy; <\/code><\/pre>\n
 and Markdown will leave it alone. But if you write: <\/p>\n
AT&T <\/code><\/pre>\n
 Markdown will translate it to: <\/p>\n
AT&amp;T <\/code><\/pre>\n
 Similarly, because Markdown supports inline HTML<\/a>, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write: <\/p>\n
4 < 5 <\/code><\/pre>\n
 Markdown will translate it to: <\/p>\n
4 &lt; 5 <\/code><\/pre>\n
 However, inside Markdown code spans and blocks, angle brackets and ampersands are always<\/em> encoded automatically. This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single <<\/code> and &<\/code> in your example code needs to be escaped.) <\/p>\n
\n
<\/span>Block Elements<\/span><\/h2>\n
<\/span>Paragraphs and Line Breaks<\/span><\/h3>\n
 A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line \u2014 a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs. The implication of the \u201cone or more consecutive lines of text\u201d rule is that Markdown supports \u201chard-wrapped\u201d text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type\u2019s \u201cConvert Line Breaks\u201d option) which translate every line break character in a paragraph into a <br \/><\/code> tag. When you do<\/em> want to insert a <br \/><\/code> break tag using Markdown, you end a line with two or more spaces, then type return. Yes, this takes a tad more effort to create a <br \/><\/code>, but a simplistic \u201cevery line break is a <br \/><\/code>\u201d rule wouldn\u2019t work for Markdown. Markdown\u2019s email-style  blockquoting<\/a> and multi-paragraph list items<\/a> work best \u2014 and look better \u2014 when you format them with hard breaks. <\/p>\n
<\/span>Headers<\/span><\/h3>\n
 Atx-style headers use 1-6 hash characters at the start of the line, corresponding to header levels 1-6. For example: <\/p>\n
# This is an H1 ## This is an H2 ###### This is an H6 <\/code><\/pre>\n
<\/span>Blockquotes<\/span><\/h3>\n
 Markdown uses email-style ><\/code> characters for blockquoting. If you\u2019re familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a ><\/code> before every line: <\/p>\n
> 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. <\/code><\/pre>\n
 Markdown allows you to be lazy and only put the ><\/code> before the first line of a hard-wrapped paragraph: <\/p>\n
> 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. <\/code><\/pre>\n
 Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of ><\/code>: <\/p>\n
> This is the first level of quoting. > > > This is nested blockquote. > > Back to the first level. <\/code><\/pre>\n
 Blockquotes can contain other Markdown elements, including headers, lists, and code blocks: <\/p>\n
> ## This is a header. > > 1. This is the first list item. > 2. This is the second list item. > > Here's some example code: > > return shell_exec(\"echo $input | $markdown_script\"); <\/code><\/pre>\n
 Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase Quote Level from the Text menu. <\/p>\n
<\/span>Lists<\/span><\/h3>\n
 Markdown supports ordered (numbered) and unordered (bulleted) lists. Unordered lists use asterisks, pluses, and hyphens \u2014 interchangably \u2014 as list markers: <\/p>\n
* Red * Green * Blue <\/code><\/pre>\n
 is equivalent to: <\/p>\n
+ Red + Green + Blue <\/code><\/pre>\n
 and: <\/p>\n
- Red - Green - Blue <\/code><\/pre>\n
 Ordered lists use numbers followed by periods: <\/p>\n
1. Bird 2. McHale 3. Parish <\/code><\/pre>\n
 List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab. To make lists look nice, you can wrap items with hanging indents: <\/p>\n
* 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. <\/code><\/pre>\n
 But if you want to be lazy, you don\u2019t have to: <\/p>\n
* 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. <\/code><\/pre>\n
 If list items are separated by blank lines, Markdown will wrap the items in <p><\/code> tags in the HTML output. For example, this input: <\/p>\n
* Bird * Magic <\/code><\/pre>\n
 will turn into: <\/p>\n
<ul> <li>Bird<\/li> <li>Magic<\/li> <\/ul> <\/code><\/pre>\n
 List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab: <\/p>\n
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. <\/code><\/pre>\n
 It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy: <\/p>\n
* 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. <\/code><\/pre>\n
 It\u2019s worth noting that it\u2019s possible to trigger an ordered list by accident, by writing something like this: <\/p>\n
1986. What a great season. <\/code><\/pre>\n
 In other words, a number-period-space<\/em> sequence at the beginning of a line. To avoid this, you can backslash-escape the period: <\/p>\n
1986\\. What a great season. <\/code><\/pre>\n
<\/span>Horizontal Rules<\/span><\/h3>\n
 You can produce a horizontal rule tag (<hr \/><\/code>) by placing three or more hyphens, asterisks, or underscores on a line by themselves. If you wish, you may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule: <\/p>\n
* * * *** ***** - - - --------------------------------------- <\/code><\/pre>\n
\n
<\/span>Span Elements<\/span><\/h2>\n
<\/span>Links<\/span><\/h3>\n
 Markdown supports two style of links: inline<\/em> and reference<\/em>. In both styles, the link text is delimited by [square brackets]. To create an inline link, use a set of regular parentheses immediately after the link text\u2019s closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an optional<\/em> title for the link, surrounded in quotes. For example: <\/p>\n
This is [an example](http:\/\/example.com\/ \"Title\") inline link. [This link](http:\/\/example.net\/) has no title attribute. <\/code><\/pre>\n
 Will produce: <\/p>\n
<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> <\/code><\/pre>\n
 If you\u2019re referring to a local resource on the same server, you can use relative paths: <\/p>\n
See my [About](\/about\/) page for details. <\/code><\/pre>\n
 Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link: <\/p>\n
This is [an example][id] reference-style link. <\/code><\/pre>\n
 You can optionally use a space to separate the sets of brackets: <\/p>\n
This is [an example] [id] reference-style link. <\/code><\/pre>\n
 Then, anywhere in the document, you define your link label like this, on a line by itself: <\/p>\n
[id]: http:\/\/example.com\/ \"Optional Title Here\" <\/code><\/pre>\n
 That is: <\/p>\n