Project: BlueCloth

Revision: 86

Author: deveiant

Date: 20 Aug 2008 17:46:31

Diff at Trac: http://www.deveiate.org/projects/BlueCloth/changeset/86

• /trunk/LICENSE.txt

  ......	@@ -1,58 +0,0 @@
  1		Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.co.jp>.
  2		You can redistribute it and/or modify it under either the terms of the GPL
  3		(see COPYING.txt file), or the conditions below:
  4
  5		1. You may make and give away verbatim copies of the source form of the
  6		software without restriction, provided that you duplicate all of the
  7		original copyright notices and associated disclaimers.
  8
  9		2. You may modify your copy of the software in any way, provided that
  10		you do at least ONE of the following:
  11
  12		a) place your modifications in the Public Domain or otherwise
  13		make them Freely Available, such as by posting said
  14		modifications to Usenet or an equivalent medium, or by allowing
  15		the author to include your modifications in the software.
  16
  17		b) use the modified software only within your corporation or
  18		organization.
  19
  20		c) rename any non-standard executables so the names do not conflict
  21		with standard executables, which must also be provided.
  22
  23		d) make other distribution arrangements with the author.
  24
  25		3. You may distribute the software in object code or executable
  26		form, provided that you do at least ONE of the following:
  27
  28		a) distribute the executables and library files of the software,
  29		together with instructions (in the manual page or equivalent)
  30		on where to get the original distribution.
  31
  32		b) accompany the distribution with the machine-readable source of
  33		the software.
  34
  35		c) give non-standard executables non-standard names, with
  36		instructions on where to get the original software distribution.
  37
  38		d) make other distribution arrangements with the author.
  39
  40		4. You may modify and include the part of the software into any other
  41		software (possibly commercial). But some files in the distribution
  42		are not written by the author, so that they are not under this terms.
  43
  44		They are gc.c(partly), utils.c(partly), regex.[ch], st.[ch] and some
  45		files under the ./missing directory. See each file for the copying
  46		condition.
  47
  48		5. The scripts and library files supplied as input to or produced as
  49		output from the software do not automatically fall under the
  50		copyright of the software, but belong to whomever generated them,
  51		and may be sold commercially, and may be aggregated with this
  52		software.
  53
  54		6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
  55		IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  56		WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  57		PURPOSE.
  58

• /trunk/project.yml

  ......	@@ -0,0 +1,20 @@
  	1	---
  	2	rubyforge_project: bluecloth
  	3	project_requirements: {}
  	4
  	5	project_description: |-
  	6	BlueCloth is a Ruby implementation of [Markdown][1], a text-to-HTML conversion
  	7	tool for web writers. To quote from the project page: Markdown allows you to
  	8	write using an easy-to-read, easy-to-write plain text format, then convert it to
  	9	structurally valid XHTML (or HTML).
  	10	rubyforge_group: deveiate
  	11	author_name: Michael Granger
  	12	project_homepage: http://deveiate.org/projects/BlueCloth/
  	13	project_dependencies: {}
  	14
  	15	project_summary: BlueCloth is a Ruby implementation of Markdown
  	16	project_name: BlueCloth
  	17	version_file: bluecloth.rb
  	18	additional_pkgfiles: []
  	19
  	20	author_email: ged@FaerieMUD.org

• /trunk/spec/data/markdowntest/Markdown Documentation - Syntax.text

  ......	@@ -0,0 +1,888 @@
  	1	Markdown: Syntax
  	2	================
  	3
  	4	<ul id="ProjectSubmenu">
  	5	<li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
  	6	<li><a href="/projects/markdown/basics" title="Markdown Basics">Basics</a></li>
  	7	<li><a class="selected" title="Markdown Syntax Documentation">Syntax</a></li>
  	8	<li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
  	9	<li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
  	10	</ul>
  	11
  	12
  	13	* [Overview](#overview)
  	14	* [Philosophy](#philosophy)
  	15	* [Inline HTML](#html)
  	16	* [Automatic Escaping for Special Characters](#autoescape)
  	17	* [Block Elements](#block)
  	18	* [Paragraphs and Line Breaks](#p)
  	19	* [Headers](#header)
  	20	* [Blockquotes](#blockquote)
  	21	* [Lists](#list)
  	22	* [Code Blocks](#precode)
  	23	* [Horizontal Rules](#hr)
  	24	* [Span Elements](#span)
  	25	* [Links](#link)
  	26	* [Emphasis](#em)
  	27	* [Code](#code)
  	28	* [Images](#img)
  	29	* [Miscellaneous](#misc)
  	30	* [Backslash Escapes](#backslash)
  	31	* [Automatic Links](#autolink)
  	32
  	33
  	34	**Note:** This document is itself written using Markdown; you
  	35	can [see the source for it by adding '.text' to the URL][src].
  	36
  	37	[src]: /projects/markdown/syntax.text
  	38
  	39	* * *
  	40
  	41	<h2 id="overview">Overview</h2>
  	42
  	43	<h3 id="philosophy">Philosophy</h3>
  	44
  	45	Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
  	46
  	47	Readability, however, is emphasized above all else. A Markdown-formatted
  	48	document should be publishable as-is, as plain text, without looking
  	49	like it's been marked up with tags or formatting instructions. While
  	50	Markdown's syntax has been influenced by several existing text-to-HTML
  	51	filters -- including [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4],
  	52	[Grutatext] [5], and [EtText] [6] -- the single biggest source of
  	53	inspiration for Markdown's syntax is the format of plain text email.
  	54
  	55	[1]: http://docutils.sourceforge.net/mirror/setext.html
  	56	[2]: http://www.aaronsw.com/2002/atx/
  	57	[3]: http://textism.com/tools/textile/
  	58	[4]: http://docutils.sourceforge.net/rst.html
  	59	[5]: http://www.triptico.com/software/grutatxt.html
  	60	[6]: http://ettext.taint.org/doc/
  	61
  	62	To this end, Markdown's syntax is comprised entirely of punctuation
  	63	characters, which punctuation characters have been carefully chosen so
  	64	as to look like what they mean. E.g., asterisks around a word actually
  	65	look like \*emphasis\*. Markdown lists look like, well, lists. Even
  	66	blockquotes look like quoted passages of text, assuming you've ever
  	67	used email.
  	68
  	69
  	70
  	71	<h3 id="html">Inline HTML</h3>
  	72
  	73	Markdown's syntax is intended for one purpose: to be used as a
  	74	format for *writing* for the web.
  	75
  	76	Markdown is not a replacement for HTML, or even close to it. Its
  	77	syntax is very small, corresponding only to a very small subset of
  	78	HTML tags. The idea is *not* to create a syntax that makes it easier
  	79	to insert HTML tags. In my opinion, HTML tags are already easy to
  	80	insert. The idea for Markdown is to make it easy to read, write, and
  	81	edit prose. HTML is a *publishing* format; Markdown is a *writing*
  	82	format. Thus, Markdown's formatting syntax only addresses issues that
  	83	can be conveyed in plain text.
  	84
  	85	For any markup that is not covered by Markdown's syntax, you simply
  	86	use HTML itself. There's no need to preface it or delimit it to
  	87	indicate that you're switching from Markdown to HTML; you just use
  	88	the tags.
  	89
  	90	The only restrictions are that block-level HTML elements -- e.g. `<div>`,
  	91	`<table>`, `<pre>`, `<p>`, etc. -- must be separated from surrounding
  	92	content by blank lines, and the start and end tags of the block should
  	93	not be indented with tabs or spaces. Markdown is smart enough not
  	94	to add extra (unwanted) `<p>` tags around HTML block-level tags.
  	95
  	96	For example, to add an HTML table to a Markdown article:
  	97
  	98	This is a regular paragraph.
  	99
  	100	<table>
  	101	<tr>
  	102	<td>Foo</td>
  	103	</tr>
  	104	</table>
  	105
  	106	This is another regular paragraph.
  	107
  	108	Note that Markdown formatting syntax is not processed within block-level
  	109	HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an
  	110	HTML block.
  	111
  	112	Span-level HTML tags -- e.g. `<span>`, `<cite>`, or `<del>` -- can be
  	113	used anywhere in a Markdown paragraph, list item, or header. If you
  	114	want, you can even use HTML tags instead of Markdown formatting; e.g. if
  	115	you'd prefer to use HTML `<a>` or `<img>` tags instead of Markdown's
  	116	link or image syntax, go right ahead.
  	117
  	118	Unlike block-level HTML tags, Markdown syntax *is* processed within
  	119	span-level tags.
  	120
  	121
  	122	<h3 id="autoescape">Automatic Escaping for Special Characters</h3>
  	123
  	124	In HTML, there are two characters that demand special treatment: `<`
  	125	and `&`. Left angle brackets are used to start tags; ampersands are
  	126	used to denote HTML entities. If you want to use them as literal
  	127	characters, you must escape them as entities, e.g. `&lt;`, and
  	128	`&amp;`.
  	129
  	130	Ampersands in particular are bedeviling for web writers. If you want to
  	131	write about 'AT&T', you need to write '`AT&amp;T`'. You even need to
  	132	escape ampersands within URLs. Thus, if you want to link to:
  	133
  	134	http://images.google.com/images?num=30&q=larry+bird
  	135
  	136	you need to encode the URL as:
  	137
  	138	http://images.google.com/images?num=30&amp;q=larry+bird
  	139
  	140	in your anchor tag `href` attribute. Needless to say, this is easy to
  	141	forget, and is probably the single most common source of HTML validation
  	142	errors in otherwise well-marked-up web sites.
  	143
  	144	Markdown allows you to use these characters naturally, taking care of
  	145	all the necessary escaping for you. If you use an ampersand as part of
  	146	an HTML entity, it remains unchanged; otherwise it will be translated
  	147	into `&amp;`.
  	148
  	149	So, if you want to include a copyright symbol in your article, you can write:
  	150
  	151	&copy;
  	152
  	153	and Markdown will leave it alone. But if you write:
  	154
  	155	AT&T
  	156
  	157	Markdown will translate it to:
  	158
  	159	AT&amp;T
  	160
  	161	Similarly, because Markdown supports [inline HTML](#html), if you use
  	162	angle brackets as delimiters for HTML tags, Markdown will treat them as
  	163	such. But if you write:
  	164
  	165	4 < 5
  	166
  	167	Markdown will translate it to:
  	168
  	169	4 &lt; 5
  	170
  	171	However, inside Markdown code spans and blocks, angle brackets and
  	172	ampersands are *always* encoded automatically. This makes it easy to use
  	173	Markdown to write about HTML code. (As opposed to raw HTML, which is a
  	174	terrible format for writing about HTML syntax, because every single `<`
  	175	and `&` in your example code needs to be escaped.)
  	176
  	177
  	178	* * *
  	179
  	180
  	181	<h2 id="block">Block Elements</h2>
  	182
  	183
  	184	<h3 id="p">Paragraphs and Line Breaks</h3>
  	185
  	186	A paragraph is simply one or more consecutive lines of text, separated
  	187	by one or more blank lines. (A blank line is any line that looks like a
  	188	blank line -- a line containing nothing but spaces or tabs is considered
  	189	blank.) Normal paragraphs should not be intended with spaces or tabs.
  	190
  	191	The implication of the "one or more consecutive lines of text" rule is
  	192	that Markdown supports "hard-wrapped" text paragraphs. This differs
  	193	significantly from most other text-to-HTML formatters (including Movable
  	194	Type's "Convert Line Breaks" option) which translate every line break
  	195	character in a paragraph into a `<br />` tag.
  	196
  	197	When you *do* want to insert a `<br />` break tag using Markdown, you
  	198	end a line with two or more spaces, then type return.
  	199
  	200	Yes, this takes a tad more effort to create a `<br />`, but a simplistic
  	201	"every line break is a `<br />`" rule wouldn't work for Markdown.
  	202	Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l]
  	203	work best -- and look better -- when you format them with hard breaks.
  	204
  	205	[bq]: #blockquote
  	206	[l]: #list
  	207
  	208
  	209
  	210	<h3 id="header">Headers</h3>
  	211
  	212	Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
  	213
  	214	Setext-style headers are "underlined" using equal signs (for first-level
  	215	headers) and dashes (for second-level headers). For example:
  	216
  	217	This is an H1
  	218	=============
  	219
  	220	This is an H2
  	221	-------------
  	222
  	223	Any number of underlining `=`'s or `-`'s will work.
  	224
  	225	Atx-style headers use 1-6 hash characters at the start of the line,
  	226	corresponding to header levels 1-6. For example:
  	227
  	228	# This is an H1
  	229
  	230	## This is an H2
  	231
  	232	###### This is an H6
  	233
  	234	Optionally, you may "close" atx-style headers. This is purely
  	235	cosmetic -- you can use this if you think it looks better. The
  	236	closing hashes don't even need to match the number of hashes
  	237	used to open the header. (The number of opening hashes
  	238	determines the header level.) :
  	239
  	240	# This is an H1 #
  	241
  	242	## This is an H2 ##
  	243
  	244	### This is an H3 ######
  	245
  	246
  	247	<h3 id="blockquote">Blockquotes</h3>
  	248
  	249	Markdown uses email-style `>` characters for blockquoting. If you're
  	250	familiar with quoting passages of text in an email message, then you
  	251	know how to create a blockquote in Markdown. It looks best if you hard
  	252	wrap the text and put a `>` before every line:
  	253
  	254	> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
  	255	> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
  	256	> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
  	257	>
  	258	> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
  	259	> id sem consectetuer libero luctus adipiscing.
  	260
  	261	Markdown allows you to be lazy and only put the `>` before the first
  	262	line of a hard-wrapped paragraph:
  	263
  	264	> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
  	265	consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
  	266	Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
  	267
  	268	> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
  	269	id sem consectetuer libero luctus adipiscing.
  	270
  	271	Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
  	272	adding additional levels of `>`:
  	273
  	274	> This is the first level of quoting.
  	275	>
  	276	> > This is nested blockquote.
  	277	>
  	278	> Back to the first level.
  	279
  	280	Blockquotes can contain other Markdown elements, including headers, lists,
  	281	and code blocks:
  	282
  	283	> ## This is a header.
  	284	>
  	285	> 1. This is the first list item.
  	286	> 2. This is the second list item.
  	287	>
  	288	> Here's some example code:
  	289	>
  	290	> return shell_exec("echo $input | $markdown_script");
  	291
  	292	Any decent text editor should make email-style quoting easy. For
  	293	example, with BBEdit, you can make a selection and choose Increase
  	294	Quote Level from the Text menu.
  	295
  	296
  	297	<h3 id="list">Lists</h3>
  	298
  	299	Markdown supports ordered (numbered) and unordered (bulleted) lists.
  	300
  	301	Unordered lists use asterisks, pluses, and hyphens -- interchangably
  	302	-- as list markers:
  	303
  	304	* Red
  	305	* Green
  	306	* Blue
  	307
  	308	is equivalent to:
  	309
  	310	+ Red
  	311	+ Green
  	312	+ Blue
  	313
  	314	and:
  	315
  	316	- Red
  	317	- Green
  	318	- Blue
  	319
  	320	Ordered lists use numbers followed by periods:
  	321
  	322	1. Bird
  	323	2. McHale
  	324	3. Parish
  	325
  	326	It's important to note that the actual numbers you use to mark the
  	327	list have no effect on the HTML output Markdown produces. The HTML
  	328	Markdown produces from the above list is:
  	329
  	330	<ol>
  	331	<li>Bird</li>
  	332	<li>McHale</li>
  	333	<li>Parish</li>
  	334	</ol>
  	335
  	336	If you instead wrote the list in Markdown like this:
  	337
  	338	1. Bird
  	339	1. McHale
  	340	1. Parish
  	341
  	342	or even:
  	343
  	344	3. Bird
  	345	1. McHale
  	346	8. Parish
  	347
  	348	you'd get the exact same HTML output. The point is, if you want to,
  	349	you can use ordinal numbers in your ordered Markdown lists, so that
  	350	the numbers in your source match the numbers in your published HTML.
  	351	But if you want to be lazy, you don't have to.
  	352
  	353	If you do use lazy list numbering, however, you should still start the
  	354	list with the number 1. At some point in the future, Markdown may support
  	355	starting ordered lists at an arbitrary number.
  	356
  	357	List markers typically start at the left margin, but may be indented by
  	358	up to three spaces. List markers must be followed by one or more spaces
  	359	or a tab.
  	360
  	361	To make lists look nice, you can wrap items with hanging indents:
  	362
  	363	* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  	364	Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
  	365	viverra nec, fringilla in, laoreet vitae, risus.
  	366	* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
  	367	Suspendisse id sem consectetuer libero luctus adipiscing.
  	368
  	369	But if you want to be lazy, you don't have to:
  	370
  	371	* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  	372	Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
  	373	viverra nec, fringilla in, laoreet vitae, risus.
  	374	* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
  	375	Suspendisse id sem consectetuer libero luctus adipiscing.
  	376
  	377	If list items are separated by blank lines, Markdown will wrap the
  	378	items in `<p>` tags in the HTML output. For example, this input:
  	379
  	380	* Bird
  	381	* Magic
  	382
  	383	will turn into:
  	384
  	385	<ul>
  	386	<li>Bird</li>
  	387	<li>Magic</li>
  	388	</ul>
  	389
  	390	But this:
  	391
  	392	* Bird
  	393
  	394	* Magic
  	395
  	396	will turn into:
  	397
  	398	<ul>
  	399	<li><p>Bird</p></li>
  	400	<li><p>Magic</p></li>
  	401	</ul>
  	402
  	403	List items may consist of multiple paragraphs. Each subsequent
  	404	paragraph in a list item must be intended by either 4 spaces
  	405	or one tab:
  	406
  	407	1. This is a list item with two paragraphs. Lorem ipsum dolor
  	408	sit amet, consectetuer adipiscing elit. Aliquam hendrerit
  	409	mi posuere lectus.
  	410
  	411	Vestibulum enim wisi, viverra nec, fringilla in, laoreet
  	412	vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
  	413	sit amet velit.
  	414
  	415	2. Suspendisse id sem consectetuer libero luctus adipiscing.
  	416
  	417	It looks nice if you indent every line of the subsequent
  	418	paragraphs, but here again, Markdown will allow you to be
  	419	lazy:
  	420
  	421	* This is a list item with two paragraphs.
  	422
  	423	This is the second paragraph in the list item. You're
  	424	only required to indent the first line. Lorem ipsum dolor
  	425	sit amet, consectetuer adipiscing elit.
  	426
  	427	* Another item in the same list.
  	428
  	429	To put a blockquote within a list item, the blockquote's `>`
  	430	delimiters need to be indented:
  	431
  	432	* A list item with a blockquote:
  	433
  	434	> This is a blockquote
  	435	> inside a list item.
  	436
  	437	To put a code block within a list item, the code block needs
  	438	to be indented *twice* -- 8 spaces or two tabs:
  	439
  	440	* A list item with a code block:
  	441
  	442	<code goes here>
  	443
  	444
  	445	It's worth noting that it's possible to trigger an ordered list by
  	446	accident, by writing something like this:
  	447
  	448	1986. What a great season.
  	449
  	450	In other words, a *number-period-space* sequence at the beginning of a
  	451	line. To avoid this, you can backslash-escape the period:
  	452
  	453	1986\. What a great season.
  	454
  	455
  	456
  	457	<h3 id="precode">Code Blocks</h3>
  	458
  	459	Pre-formatted code blocks are used for writing about programming or
  	460	markup source code. Rather than forming normal paragraphs, the lines
  	461	of a code block are interpreted literally. Markdown wraps a code block
  	462	in both `<pre>` and `<code>` tags.
  	463
  	464	To produce a code block in Markdown, simply indent every line of the
  	465	block by at least 4 spaces or 1 tab. For example, given this input:
  	466
  	467	This is a normal paragraph:
  	468
  	469	This is a code block.
  	470
  	471	Markdown will generate:
  	472
  	473	<p>This is a normal paragraph:</p>
  	474
  	475	<pre><code>This is a code block.
  	476	</code></pre>
  	477
  	478	One level of indentation -- 4 spaces or 1 tab -- is removed from each
  	479	line of the code block. For example, this:
  	480
  	481	Here is an example of AppleScript:
  	482
  	483	tell application "Foo"
  	484	beep
  	485	end tell
  	486
  	487	will turn into:
  	488
  	489	<p>Here is an example of AppleScript:</p>
  	490
  	491	<pre><code>tell application "Foo"
  	492	beep
  	493	end tell
  	494	</code></pre>
  	495
  	496	A code block continues until it reaches a line that is not indented
  	497	(or the end of the article).
  	498
  	499	Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
  	500	are automatically converted into HTML entities. This makes it very
  	501	easy to include example HTML source code using Markdown -- just paste
  	502	it and indent it, and Markdown will handle the hassle of encoding the
  	503	ampersands and angle brackets. For example, this:
  	504
  	505	<div class="footer">
  	506	&copy; 2004 Foo Corporation
  	507	</div>
  	508
  	509	will turn into:
  	510
  	511	<pre><code>&lt;div class="footer"&gt;
  	512	&amp;copy; 2004 Foo Corporation
  	513	&lt;/div&gt;
  	514	</code></pre>
  	515
  	516	Regular Markdown syntax is not processed within code blocks. E.g.,
  	517	asterisks are just literal asterisks within a code block. This means
  	518	it's also easy to use Markdown to write about Markdown's own syntax.
  	519
  	520
  	521
  	522	<h3 id="hr">Horizontal Rules</h3>
  	523
  	524	You can produce a horizontal rule tag (`<hr />`) by placing three or
  	525	more hyphens, asterisks, or underscores on a line by themselves. If you
  	526	wish, you may use spaces between the hyphens or asterisks. Each of the
  	527	following lines will produce a horizontal rule:
  	528
  	529	* * *
  	530
  	531	***
  	532
  	533	*****
  	534
  	535	- - -
  	536
  	537	---------------------------------------
  	538
  	539	_ _ _
  	540
  	541
  	542	* * *
  	543
  	544	<h2 id="span">Span Elements</h2>
  	545
  	546	<h3 id="link">Links</h3>
  	547
  	548	Markdown supports two style of links: *inline* and *reference*.
  	549
  	550	In both styles, the link text is delimited by [square brackets].
  	551
  	552	To create an inline link, use a set of regular parentheses immediately
  	553	after the link text's closing square bracket. Inside the parentheses,
  	554	put the URL where you want the link to point, along with an *optional*
  	555	title for the link, surrounded in quotes. For example:
  	556
  	557	This is [an example](http://example.com/ "Title") inline link.
  	558
  	559	[This link](http://example.net/) has no title attribute.
  	560
  	561	Will produce:
  	562
  	563	<p>This is <a href="http://example.com/" title="Title">
  	564	an example</a> inline link.</p>
  	565
  	566	<p><a href="http://example.net/">This link</a> has no
  	567	title attribute.</p>
  	568
  	569	If you're referring to a local resource on the same server, you can
  	570	use relative paths:
  	571
  	572	See my [About](/about/) page for details.
  	573
  	574	Reference-style links use a second set of square brackets, inside
  	575	which you place a label of your choosing to identify the link:
  	576
  	577	This is [an example][id] reference-style link.
  	578
  	579	You can optionally use a space to separate the sets of brackets:
  	580
  	581	This is [an example] [id] reference-style link.
  	582
  	583	Then, anywhere in the document, you define your link label like this,
  	584	on a line by itself:
  	585
  	586	[id]: http://example.com/ "Optional Title Here"
  	587
  	588	That is:
  	589
  	590	* Square brackets containing the link identifier (optionally
  	591	indented from the left margin using up to three spaces);
  	592	* followed by a colon;
  	593	* followed by one or more spaces (or tabs);
  	594	* followed by the URL for the link;
  	595	* optionally followed by a title attribute for the link, enclosed
  	596	in double or single quotes.
  	597
  	598	The link URL may, optionally, be surrounded by angle brackets:
  	599
  	600	[id]: <http://example.com/> "Optional Title Here"
  	601
  	602	You can put the title attribute on the next line and use extra spaces
  	603	or tabs for padding, which tends to look better with longer URLs:
  	604
  	605	[id]: http://example.com/longish/path/to/resource/here
  	606	"Optional Title Here"
  	607
  	608	Link definitions are only used for creating links during Markdown
  	609	processing, and are stripped from your document in the HTML output.
  	610
  	611	Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are *not* case sensitive. E.g. these two links:
  	612
  	613	[link text][a]
  	614	[link text][A]
  	615
  	616	are equivalent.
  	617
  	618	The *implicit link name* shortcut allows you to omit the name of the
  	619	link, in which case the link text itself is used as the name.
  	620	Just use an empty set of square brackets -- e.g., to link the word
  	621	"Google" to the google.com web site, you could simply write:
  	622
  	623	[Google][]
  	624
  	625	And then define the link:
  	626
  	627	[Google]: http://google.com/
  	628
  	629	Because link names may contain spaces, this shortcut even works for
  	630	multiple words in the link text:
  	631
  	632	Visit [Daring Fireball][] for more information.
  	633
  	634	And then define the link:
  	635
  	636	[Daring Fireball]: http://daringfireball.net/
  	637
  	638	Link definitions can be placed anywhere in your Markdown document. I
  	639	tend to put them immediately after each paragraph in which they're
  	640	used, but if you want, you can put them all at the end of your
  	641	document, sort of like footnotes.
  	642
  	643	Here's an example of reference links in action:
  	644
  	645	I get 10 times more traffic from [Google] [1] than from
  	646	[Yahoo] [2] or [MSN] [3].
  	647
  	648	[1]: http://google.com/ "Google"
  	649	[2]: http://search.yahoo.com/ "Yahoo Search"
  	650	[3]: http://search.msn.com/ "MSN Search"
  	651
  	652	Using the implicit link name shortcut, you could instead write:
  	653
  	654	I get 10 times more traffic from [Google][] than from
  	655	[Yahoo][] or [MSN][].
  	656
  	657	[google]: http://google.com/ "Google"
  	658	[yahoo]: http://search.yahoo.com/ "Yahoo Search"
  	659	[msn]: http://search.msn.com/ "MSN Search"
  	660
  	661	Both of the above examples will produce the following HTML output:
  	662
  	663	<p>I get 10 times more traffic from <a href="http://google.com/"
  	664	title="Google">Google</a> than from
  	665	<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
  	666	or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
  	667
  	668	For comparison, here is the same paragraph written using
  	669	Markdown's inline link style:
  	670
  	671	I get 10 times more traffic from [Google](http://google.com/ "Google")
  	672	than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
  	673	[MSN](http://search.msn.com/ "MSN Search").
  	674
  	675	The point of reference-style links is not that they're easier to
  	676	write. The point is that with reference-style links, your document
  	677	source is vastly more readable. Compare the above examples: using
  	678	reference-style links, the paragraph itself is only 81 characters
  	679	long; with inline-style links, it's 176 characters; and as raw HTML,
  	680	it's 234 characters. In the raw HTML, there's more markup than there
  	681	is text.
  	682
  	683	With Markdown's reference-style links, a source document much more
  	684	closely resembles the final output, as rendered in a browser. By
  	685	allowing you to move the markup-related metadata out of the paragraph,
  	686	you can add links without interrupting the narrative flow of your
  	687	prose.
  	688
  	689
  	690	<h3 id="em">Emphasis</h3>
  	691
  	692	Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
  	693	emphasis. Text wrapped with one `*` or `_` will be wrapped with an
  	694	HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML
  	695	`<strong>` tag. E.g., this input:
  	696
  	697	*single asterisks*
  	698
  	699	_single underscores_
  	700
  	701	**double asterisks**
  	702
  	703	__double underscores__
  	704
  	705	will produce:
  	706
  	707	<em>single asterisks</em>
  	708
  	709	<em>single underscores</em>
  	710
  	711	<strong>double asterisks</strong>
  	712
  	713	<strong>double underscores</strong>
  	714
  	715	You can use whichever style you prefer; the lone restriction is that
  	716	the same character must be used to open and close an emphasis span.
  	717
  	718	Emphasis can be used in the middle of a word:
  	719
  	720	un*fucking*believable
  	721
  	722	But if you surround an `*` or `_` with spaces, it'll be treated as a
  	723	literal asterisk or underscore.
  	724
  	725	To produce a literal asterisk or underscore at a position where it
  	726	would otherwise be used as an emphasis delimiter, you can backslash
  	727	escape it:
  	728
  	729	\*this text is surrounded by literal asterisks\*
  	730
  	731
  	732
  	733	<h3 id="code">Code</h3>
  	734
  	735	To indicate a span of code, wrap it with backtick quotes (`` ` ``).
  	736