Markdown: Difference between revisions
revert - not an improvement |
→Syntax examples: Added information to the syntax of Markdown. |
||
Line 51: | Line 51: | ||
#### Fourth-level heading |
#### Fourth-level heading |
||
This would translate into: |
|||
<source lang="html4strict"> |
|||
<h1>First-level heading</h1> |
|||
<h4>Fourth-level heading</h4> |
|||
</source> |
|||
Optionally, headings may be "closed" with hashes that need not match the number of hashes placed at the front of a header, purely for cosmetic purposes. |
Optionally, headings may be "closed" with hashes that need not match the number of hashes placed at the front of a header, purely for cosmetic purposes. |
||
Line 59: | Line 65: | ||
## Second-level heading #### |
## Second-level heading #### |
||
The first two heading levels also have an alternative syntax: |
|||
The first two heading levels can use an alternative syntax: |
|||
<pre style="font-family: monospace;"> |
|||
First-level heading |
|||
=================== |
|||
First-level heading |
|||
=================== |
|||
-------------------- |
|||
</pre> |
|||
Second-level heading |
|||
-------------------- |
|||
===Paragraphs=== |
===Paragraphs=== |
||
A paragraph is one or more consecutive lines of text separated by one or more blank lines. Normal paragraphs should not be indented with spaces or tabs |
A paragraph is one or more consecutive lines of text separated by one or more blank lines. Normal paragraphs should not be indented with spaces or tabs. |
||
This is a paragraph. It has two sentences. |
|||
This is another paragraph. It also has |
|||
two sentences. |
|||
The following example translates into: |
|||
This is another paragraph. It also has |
|||
<source lang="html4strict"> |
|||
two sentences.</nowiki></pre> |
|||
<p>This is a paragraph. It has two sentences.</p> |
|||
<p>This is another paragraph. It also has two sentences.</p> |
|||
</source> |
|||
===Line breaks=== |
|||
To insert a linebreak, end a line with two or more spaces followed by a return. For example (using visible space notation): |
|||
def␣show_results␣␣ |
|||
end |
|||
This translates into: |
|||
<source lang="html4strict"> |
|||
def show_results<br /> end |
|||
</source> |
|||
===Lists=== |
===Lists=== |
||
There are two types of lists in Markdown, an ordered list and an unordered list, as in [[HTML]]. |
|||
An unordered list is created by placing a number of indents and "bullets" infront of the list item. "Bullets" include asterisks, plus and minus signs. |
|||
* An item in a bulleted (unordered) list |
* An item in a bulleted (unordered) list |
||
+ A subitem, indented with 4 spaces |
|||
- Another item in a bulleted list |
|||
* Here's another item |
|||
This translates into: |
|||
<source lang="html4strict"> |
|||
<ul> |
|||
<li>An item in a bulleted (unordered) list |
|||
<ul> |
|||
<li>A subitem, indented with 4 spaces</li> |
|||
</ul> |
|||
</li> |
|||
<li>Another item in a bulleted list</li> |
|||
<li>Here's another item</li> |
|||
</ul> |
|||
</source> |
|||
In an ordered list, numbers need not match the order of elements. |
In an ordered list, numbers need not match the order of elements. |
||
Line 89: | Line 128: | ||
9. Another item |
9. Another item |
||
5. Yet another item |
5. Yet another item |
||
This translates into: |
|||
<source lang="html4strict"> |
|||
<ol> |
|||
<li>An item in an enumerated (ordered) list |
|||
<ol> |
|||
<li>A subitem, indented with 4 spaces</li> |
|||
</ol> |
|||
</li> |
|||
<li>Another item in an enumerated list</li> |
|||
<li>Another item</li> |
|||
<li>Yet another item</li> |
|||
</ol> |
|||
</source> |
|||
If blank lines are placed between items, they will be parsed as paragraphs. Multi-paragraph list items can be created by indenting the paragraphs by 4 spaces or 1 tab. For example, |
|||
* A list item |
|||
With multiple paragraphs |
|||
* Another item |
|||
translates into: |
|||
<source lang="html4strict"> |
|||
<ul> |
|||
<li><p>A list item</p><p>With multiple paragraphs</p></li> |
|||
<li>Another item</li> |
|||
</ul> |
|||
</source> |
|||
===Emphasized text=== |
===Emphasized text=== |
||
Emphasized text can have multiple syntaxes, either enclosed with asterisks or underscores. |
|||
*emphasis* '''or''' _emphasis_ ''(e.g., italics)'' |
|||
Enclosing with a single asterisk or underscore represents italics. |
|||
**strong emphasis** '''or''' __strong emphasis__ '''(e.g., boldface)''' |
|||
*emphasis (italic)* or _emphasis (italic)_ |
|||
This translates into: |
|||
<source lang="html4strict"> |
|||
<em>emphasis (italic)</em> or <em>emphasis (italic)</em> |
|||
</source> |
|||
Enclosing with two asterisks or underscores represents boldface. |
|||
**strong emphasis (boldface)** or __strong emphasis (boldface)__ |
|||
This translates into: |
|||
<source lang="html4strict"> |
|||
<strong>strong emphasis (boldface)</strong> or <strong>strong emphasis (boldface)</strong> |
|||
</source> |
|||
Enclosing with three of either represents both italics and boldface. |
|||
***very strong emphasis (italic and boldface)*** or ___very strong emphasis (italic and boldface)___ ''' |
|||
This translates into: |
|||
<source lang="html4strict"> |
|||
<strong><em>very strong emphasis (italic and boldface)</em></strong> or <strong><em>very strong emphasis (italic and boldface)</em></strong> |
|||
</source> |
|||
===Code=== |
===Code=== |
||
To include code (formatted in monospace font), you can either |
To include code (formatted in [[Monospaced font|monospace font]]), you can either surround inline code with backticks (`) or indent several lines of code by at least four spaces. |
||
surround inline code with backticks (`), like in |
|||
Backticks can be used in a sentence to represent code. |
|||
Some text with `some code` inside, |
|||
Some text with `some code` inside |
|||
or indent several lines of code by at least four spaces, as in: |
|||
This translates into: |
|||
<source lang="html4strict"> |
|||
Some text with <code>some code</code> inside |
|||
</source> |
|||
Multiline code or longer pieces of code should be indented by four spaces. |
|||
<pre> |
<pre> |
||
line 1 of code |
line 1 of code |
||
Line 105: | Line 206: | ||
line 3 of code |
line 3 of code |
||
</pre> |
</pre> |
||
The latter option makes Markdown retain all whitespace—as opposed |
|||
to the usual behaviour, which, by removing line breaks and excess |
|||
spaces, would break indentation and code layout. |
|||
This translates into: |
|||
===Line breaks=== |
|||
<source lang="html4strict"> |
|||
To insert a linebreak, end a line with two or more spaces followed by a return. For example (using visible space notation): |
|||
<pre> |
|||
def␣show_results␣␣ |
|||
<code> |
|||
end |
|||
line 1 of code |
|||
line 2 of code |
|||
line 3 of code |
|||
</code> |
|||
</pre> |
|||
</source> |
|||
The latter option makes Markdown retain all whitespace—as opposed to the usual behaviour, which, by removing line breaks and excess spaces, would break indentation and code layout. |
|||
A blank line between lines of text separates paragraphs. For example: |
|||
sentence A |
|||
sentence B |
|||
===Blockquotes=== |
===Blockquotes=== |
||
Blockquotes are created by adding an angle bracket. For example: |
|||
> "This entire paragraph of text will be enclosed in an HTML blockquote element. |
> "This entire paragraph of text will be enclosed in an HTML blockquote element. |
||
Blockquote elements are reflowable. You may arbitrarily |
Blockquote elements are reflowable. You may arbitrarily |
||
Line 133: | Line 236: | ||
===External links=== |
===External links=== |
||
Links may be included inline |
Links may be included inline, with the link text enclosed in square brackets and the link address enclosed in round brackets. |
||
[link text here](link.address.here) |
[link text here](link.address.here) |
||
Ex. [Markdown](<nowiki>http://en.wikipedia.com/wiki/Markdown</nowiki>) |
Ex. [Markdown](<nowiki>http://en.wikipedia.com/wiki/Markdown</nowiki>) |
||
This translates into: |
|||
Alternatively, links can be placed in footnotes outside of the paragraph, being referenced with some sort of reference tag. For example, including the following inline: |
|||
<source lang="html4strict"> |
|||
<a href="http://en.wikipedia.com/wiki/Markdown">Markdown</a> |
|||
</source> |
|||
Alternatively, links can be placed in footnotes outside of the paragraph, being referenced with a reference tag. For example, including the following inline: |
|||
[link text here][linkref] |
[link text here][linkref] |
||
Line 147: | Line 255: | ||
===Images=== |
===Images=== |
||
Images have similar syntax to links with a preceding exclamation point. |
Images have a similar syntax to links with a preceding exclamation point. |
||
![Alt text](/path/to/img.jpg) |
![Alt text](/path/to/img.jpg) |
||
This translates into: |
|||
Or: |
|||
<source lang="html4strict"> |
|||
<img src="/path/to/img.jpg" alt="Alt text" /> |
|||
</source> |
|||
An optional title can be added to the end of the link address, enclosed in double quotes, as shown here: |
|||
![Alt text](/path/to/img.jpg "Optional title") |
![Alt text](/path/to/img.jpg "Optional title") |
||
This translates into: |
|||
Like links, images also have a footnote style syntax |
|||
<source lang="html4strict"> |
|||
<img src="/path/to/img.jpg" alt="Alt text" title="Optional title" /> |
|||
</source> |
|||
Like links, images may also have a footnote style syntax. |
|||
![Alt text][id] |
![Alt text][id] |
||
Line 171: | Line 289: | ||
- - - |
- - - |
||
--------------------------------------- |
--------------------------------------- |
||
All of these will translate into a HTML horizontal rule tag. |
|||
==Editors== |
==Editors== |
Revision as of 07:30, 16 May 2013
![]() | This article is written like a manual or guide. (May 2010) |
Filename extension |
.md |
---|---|
Internet media type | text/markdown |
Developed by | John Gruber and Aaron Swartz |
Initial release | March 25, 2004[1] |
Latest release | 1.0.1 December 17, 2004[2] |
Type of format | Markup language |
Free format? | yes[3] |
Website | daringfireball |
Markdown is a lightweight markup language, originally created by John Gruber with substantial contributions from Aaron Swartz, allowing people “to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML)”.[2] The language takes many cues from existing conventions for marking up plain text in email. In other words, Markdown is a text-to-HTML conversion tool (for web writers).
Markdown is also a Perl script written by Gruber, Markdown.pl, which converts marked-up text input to valid, well-formed XHTML or HTML and replaces left-pointing angle brackets ('<') and ampersands with their corresponding character entity references. It can be used as a standalone script, as a plugin for Blosxom or Movable Type, or as a text filter for BBEdit.[2]
Markdown has since been re-implemented by others as a Perl module available on CPAN (Text::Markdown), and in a variety of other programming languages. It is distributed under a BSD-style license[3] and is included with, or available as a plugin for, several content-management systems.[4][5]
Sites such as GitHub, reddit, Stack Overflow and SourceForge use Markdown to facilitate discussion between users.[6][7][8][9]
Syntax examples
This is not an exhaustive listing of Markdown's syntax, and in many cases multiple styles of syntax are available to accomplish a particular effect. See the full Markdown syntax for more information. Characters which are ordinarily interpreted by Markdown as formatting commands will instead be interpreted literally if preceded by a backslash; for example, the sequence '\*' would output an asterisk rather than beginning a span of emphasized text. Markdown also does not transform any text within a "raw" block-level XHTML element; thus it is possible to include sections of XHTML within a Markdown source document by wrapping them in block-level XHTML tags.
Headings
HTML headings are produced by placing a number of hashes before the header text corresponding to the level of heading desired (HTML offers six levels of headings), like so:
# First-level heading #### Fourth-level heading
This would translate into:
<h1>First-level heading</h1>
<h4>Fourth-level heading</h4>
Optionally, headings may be "closed" with hashes that need not match the number of hashes placed at the front of a header, purely for cosmetic purposes.
# First-level heading # #### Fourth-level heading #### ## Second-level heading ####
The first two heading levels can use an alternative syntax:
First-level heading =================== Second-level heading --------------------
Paragraphs
A paragraph is one or more consecutive lines of text separated by one or more blank lines. Normal paragraphs should not be indented with spaces or tabs.
This is a paragraph. It has two sentences. This is another paragraph. It also has two sentences.
The following example translates into:
<p>This is a paragraph. It has two sentences.</p>
<p>This is another paragraph. It also has two sentences.</p>
Line breaks
To insert a linebreak, end a line with two or more spaces followed by a return. For example (using visible space notation):
def␣show_results␣␣ end
This translates into:
def show_results<br /> end
Lists
There are two types of lists in Markdown, an ordered list and an unordered list, as in HTML.
An unordered list is created by placing a number of indents and "bullets" infront of the list item. "Bullets" include asterisks, plus and minus signs.
* An item in a bulleted (unordered) list + A subitem, indented with 4 spaces - Another item in a bulleted list * Here's another item
This translates into:
<ul>
<li>An item in a bulleted (unordered) list
<ul>
<li>A subitem, indented with 4 spaces</li>
</ul>
</li>
<li>Another item in a bulleted list</li>
<li>Here's another item</li>
</ul>
In an ordered list, numbers need not match the order of elements.
1. An item in an enumerated (ordered) list 1. A subitem, indented with 4 spaces 2. Another item in an enumerated list 9. Another item 5. Yet another item
This translates into:
<ol>
<li>An item in an enumerated (ordered) list
<ol>
<li>A subitem, indented with 4 spaces</li>
</ol>
</li>
<li>Another item in an enumerated list</li>
<li>Another item</li>
<li>Yet another item</li>
</ol>
If blank lines are placed between items, they will be parsed as paragraphs. Multi-paragraph list items can be created by indenting the paragraphs by 4 spaces or 1 tab. For example,
* A list item
With multiple paragraphs
* Another item
translates into:
<ul>
<li><p>A list item</p><p>With multiple paragraphs</p></li>
<li>Another item</li>
</ul>
Emphasized text
Emphasized text can have multiple syntaxes, either enclosed with asterisks or underscores.
Enclosing with a single asterisk or underscore represents italics.
*emphasis (italic)* or _emphasis (italic)_
This translates into:
<em>emphasis (italic)</em> or <em>emphasis (italic)</em>
Enclosing with two asterisks or underscores represents boldface.
**strong emphasis (boldface)** or __strong emphasis (boldface)__
This translates into:
<strong>strong emphasis (boldface)</strong> or <strong>strong emphasis (boldface)</strong>
Enclosing with three of either represents both italics and boldface.
***very strong emphasis (italic and boldface)*** or ___very strong emphasis (italic and boldface)___
This translates into:
<strong><em>very strong emphasis (italic and boldface)</em></strong> or <strong><em>very strong emphasis (italic and boldface)</em></strong>
Code
To include code (formatted in monospace font), you can either surround inline code with backticks (`) or indent several lines of code by at least four spaces.
Backticks can be used in a sentence to represent code.
Some text with `some code` inside
This translates into:
Some text with <code>some code</code> inside
Multiline code or longer pieces of code should be indented by four spaces.
line 1 of code line 2 of code line 3 of code
This translates into:
<pre>
<code>
line 1 of code
line 2 of code
line 3 of code
</code>
</pre>
The latter option makes Markdown retain all whitespace—as opposed to the usual behaviour, which, by removing line breaks and excess spaces, would break indentation and code layout.
Blockquotes
Blockquotes are created by adding an angle bracket. For example:
> "This entire paragraph of text will be enclosed in an HTML blockquote element. Blockquote elements are reflowable. You may arbitrarily wrap the text to your liking, and it will all be parsed into a single blockquote element."
The above would translate into the following HTML:
<blockquote><p>This entire paragraph of text will be enclosed in an HTML blockquote element. Blockquote
elements are reflowable. You may arbitrarily wrap the text to your liking, and it will all
be parsed into a single blockquote element.</p></blockquote>
External links
Links may be included inline, with the link text enclosed in square brackets and the link address enclosed in round brackets.
[link text here](link.address.here) Ex. [Markdown](http://en.wikipedia.com/wiki/Markdown)
This translates into:
<a href="http://en.wikipedia.com/wiki/Markdown">Markdown</a>
Alternatively, links can be placed in footnotes outside of the paragraph, being referenced with a reference tag. For example, including the following inline:
[link text here][linkref]
would produce a link if the following showed up outside of the paragraph (or at the end of the document):
[linkref]: link.address.here "link title here"
Images
Images have a similar syntax to links with a preceding exclamation point.
![Alt text](/path/to/img.jpg)
This translates into:
<img src="/path/to/img.jpg" alt="Alt text" />
An optional title can be added to the end of the link address, enclosed in double quotes, as shown here:
![Alt text](/path/to/img.jpg "Optional title")
This translates into:
<img src="/path/to/img.jpg" alt="Alt text" title="Optional title" />
Like links, images may also have a footnote style syntax.
![Alt text][id]
with a reference later in the document defining the URL location.
[id]: url/to/image "Optional title attribute"
Horizontal rules
Horizontal rules are created by placing three or more hyphens, asterisks, or underscores on a line by themselves. You may use spaces between the hyphens or asterisks. Each of the following lines will produce a horizontal rule:
* * * *** ***** - - - ---------------------------------------
All of these will translate into a HTML horizontal rule tag.
Editors
While Markdown is a minimal markup language and is easily read and edited with a normal text editor there are special designed editors which preview the files direct with styles. There are a variety of such editors available for all of the major platforms. There are syntax highlighting plugins for markdown built into gedit and vim.
Implementations
Implementations of Markdown are available for many different frameworks, platforms and languages.
- The sourcecode documentation generator Doxygen supports Markdown with extra features [10].
- RStudio, an IDE for R provides a C++ wrapper function for the markdown implementation sundown.[11]
- IntelliJ IDEA, an IDE for Java, provides a Markdown plugin[12][13]
- MultiMarkdown A format and program with more syntax features and export options than traditional Markdown
There are many more open-source software implementations of Markdown available online.
Standardization
There are no clearly defined Markdown standard, apart from the original writeup and implementation by John Gruber. In late 2012, a standardization effort was started, spurred in part by a blog post of Jeff Atwood.[14] A community website now aims to "document various tools and resources available to document authors and developers, as well as implementors of the various markdown implementations".[15] A tool (named Babelmark2[16]) is also available to "[compare] the output of various implementations" to "promote discussion of how and whether certain vague aspects of the markdown spec should be clarified".[17]
See also
- Comparison of document markup languages
- Comparison of documentation generators
- Markdown extensions
- Markdown Extra
- Org-mode has similar lightweight markup.
- reStructuredText, a similar lightweight markup, also used for Python documentation.
- Textile, a similar lightweight markup language to produce HTML.
- AsciiDoc, a similar lightweight markup language supporting many types of documents.
- txt2tags, another lightweight markup language.
- Setext, an old lightweight markup language (1992).
References
- ^ http://web.archive.org/web/20040402182332/http://daringfireball.net/projects/markdown/
- ^ a b c Markdown 1.0.1 readme source code "Daring Fireball - Markdown". 17-Dec-2004.
{{cite web}}
: Check date values in:|date=
(help) - ^ a b http://daringfireball.net/projects/markdown/license
- ^ "MarsEdit 2.3 ties the knot with Tumblr support - Ars Technica". Retrieved 2009-08-11.
- ^ "Review: Practical Django Projects - Ars Technica". Retrieved 2009-08-11.
- ^ "GitHub Flavored Markdown". github.com. Retrieved 29 March 2013.
- ^ "Reddit markdown primer. Or, how do you do all that fancy formatting in your comments, anyway?". reddit.com. Retrieved 29 March 2013.
- ^ "Markdown help". http://stackoverflow.com. Retrieved 29 March 2013.
{{cite web}}
: External link in
(help)|publisher=
- ^ "SourceForge: Markdown Syntax Guide". sourceforge.net. Retrieved 2013-05-10.
- ^ http://www.stack.nl/~dimitri/doxygen/manual/markdown.html
- ^ https://github.com/rstudio/rstudio/blob/master/src/cpp/core/markdown/Markdown.cpp
- ^ http://plugins.jetbrains.com/plugin?id=5970
- ^ https://github.com/nicoulaj/idea-markdown
- ^ http://www.codinghorror.com/blog/2012/10/the-future-of-markdown.html
- ^ http://markdown.github.io/
- ^ http://johnmacfarlane.net/babelmark2/
- ^ http://johnmacfarlane.net/babelmark2/faq.html