Lightweight Markup: Markdown, reStructuredText, MediaWiki, AsciiDoc, Org-mode

markup: text style | grouping and alignment | images | tables, code, and math

tools: pandoc

markdown restructured text mediawiki asciidoc org-mode
sandbox daringfireball.net/projects/markdown/dingus

johnmacfarlane.net/pandoc/try		 rst.ninjs.org en.wikipedia.org/wiki/Wikipedia:Sandbox asciidoc.wiki.com/wiki/Template:Sandbox
command line tool $ apt install markdown
$ markdown foo.txt > foo.html

$ apt install pandoc
$ pandoc foo.txt -o foo.html		 $ pip install rst2html5

$ rst2html5 foo.rst > foo.html		 run at root of MediaWiki source tree:

$ php maintenance/parse.php foo.txt \
  > foo.html		 $ apt install asciidoc
$ asciidoc foo.txt
autolinks url?
 		 no yes yes yes yes
can use html entities? yes; they are passed to output html no, the ampersand will be html entity escaped yes; they are replaced by UTF-8 yes; they are passed to output html
encoding markdown and pandoc assume UTF-8 for input and output. default output is UTF-8; default input is system dependent

$ rst2html5 --input-encoding=utf-8 \
  --output-encoding=iso8859-1 \
  < foo.rst > foo.html		 MediaWiki specifies UTF-8 in the response header and the HTML document. It handles UTF-8 POST requests, and may handle other encodings correctly. assumes UTF-8 for input and output
link offsite
 		 [Website](http://website.com) `Website <http://website.com>`_ [http://website.com Website] http://website.com[Website] [[http://www.google.com][Google]]
link with url in footnote link:
[Website][u1]

footnote:
[u1]: http://website.com		 link:
Website_

footnote:
.. _Website: http://website.com
link onsite <a href="page">Pipe Trick</a> [[page|Pipe Trick]] link:page.html[Pipe Trick]
define anchor <a name="foo"/> .. _foo: Headers automatically get anchors. Also:
<div id="foo"></div>		 anchor:foo[] #+NAME: foo
link to anchor <a href="#foo">Foo</a>

pandoc extension:
[Foo](#foo)		 Links to "_foo"; "foo" is used for text:
foo_		 [[#foo|Foo]] <<anchor:foo,Foo>> [[foo][Foo]]
comment <!-- comment --> .. comment
   another comment

blank line terminates comment		 <!-- comment --> // comment whitespace only before number sign:

# comment
HTML set off block level html tags with blank lines:

<h1>My Header</h1>
 		 |my_header|

this must exist elsewhere in document:
.. |my_header| raw:: html

  <h1>foo</h1>		 some HTML tags are permitted
text style
markdown restructured text mediawiki asciidoc org-mode
italic text *italic text*
_italic text_		 *italic text* two single quotes:
''italic text''		 'italic text'
_italic text_		 /italic text/
bold text **bold text**
__bold text__		 **bold text** three single quotes:
'''bold text'''		 *bold text* *bold text*
small caps text <span style="font-variant: small-caps">
small caps text
</span>		 {{smallcaps|small caps text}}
fixed width text `fixed width text` ``fixed width text`` <tt>fixed width text</tt> +fixed width text+ ~fixed wdith text~
underlined text <span style="text-decoration: underline">underlined text</span> <u>underlined text</u> [underline]#underlined text# _underlined text_
striketrhough text <del>strikethough text</del> <del>strikethough text</del> +strikethrough text+
literal text \*not italics\*
`*not italics*`		 \*not italics\* <nowiki>''not italics''</nowiki> +++_not italics_+++
superscript2 superscript<sup>2</sup> superscript<sup>2</sup> superscript^2^
subscript2 subscript<sub>2</sub> subscript<sub>2</sub> subscript~2~
font color <span style="color: red">font color</span> <font color="red">font color</font> [red]#font color#
font size <font size=16>foo</font> <font size="16">foo</font>
span w/ class <span class="foo">
text
</span>		 .. role:: foo

:foo:`text`		 <span class="foo">
text
</span>
grouping and alignment
markdown restructured text mediawiki asciidoc org-mode
line break space, space, newline

 all lines in paragraph with line breaks must start with pipe:

| the line breaks
| here		 <br/> space, plus, newline
 +		 backslash, backslash, newline

i.e put \\ at the end of the line
horizontal rule three or more asterisks, hyphens, or underscores:
***
---
___		 four or more punctuation characters set off by blank lines:

----		 four or more hyphens:
----		 three or more single quotes
'''		 five or more hyphens on a line by themselves:

-----
document title pandoc extension:
% document title		 ==============
document title
==============		 = document title =

document title
==============
document header % document title
% John Doe; Jane Roe
% August 16, 2001
 :Date: 2001-08-16
:Version: 1
:Authors: - John Doe
          - Jane Roe		 document title
==============
John Doe
August 16, 2001
section header pandoc requires blank line before header, markdown doesn't:
# section header

section header
==============		 Other punctuation can be used for title and headers. Whatever punctuation is used must be used consistently in the document. An n+1 level section must be contained in an n level section.
section header
==============		 =section header= == section header ==

section header
--------------		 no indentation before asterisk:

* section header
subsection header ## subsection header

subsection header
-----------------		 subsection header
-----------------		 ==subsection header== === subsection header ===

subsection header
~~~~~~~~~~~~~~~~~		 no indentation before asterisk:

** subsection header
subsubsection header ### subsubsection header subsubsection header
~~~~~~~~~~~~~~~~~~~~		 ===subsubsection header=== ==== subsubsection header ====

subsubsection header
^^^^^^^^^^^^^^^^^^^^		 no indentation before asterisk:

*** subusbsection header
level 4 header #### level 4 header level 4 header
``````````````		 ====level 4 header====
headers automatically anchored? markdown no, pandoc yes

pandoc header identifiers are the same as the header with (1) all punctuation except hyphens, underscores, periods removed, (2) spaces and newlines replaced by hyphens, (3) lowercase, (4) everything before first letter removed		 yes yes yes, with id attribute on header element yes, with id attribute on header element

example: <h4 id="sec-1-1-1">
list item pandoc requires sublists be indented 4 spaces:
* list item
    * sublist item

plus signs + or hyphens - may be used in place of asterisks		 sublist must be set off by a blank line:

- list item

  - sublist item

asterisks * or plus signs + may be used in place of hyphens -		 * list item
** sublist item		 * list item
** sublist item		 + list item
  + sublist item
  + sublist item

Hyphens and asterisks can also be used for bullets. If asterisks are used, they must be indented to distinguish them from section headers.
list item with multiple paragraphs pandoc requires 4 space indent:
  * 1st list item

    2nd paragraph

  * 2nd list item		 * 1st list item<br/><br/>2nd paragraph
* 2nd list item		 + 1st list item

  2nd paragraph

+ 2nd list item
numbered list item markdown ignores actual numeric values; pandoc uses first value only:
1. numbered one
2. numbered two

pandoc supports other formats:
1) numbered one
2) numbered two

i. roman numeral one
ii. roman numeral two		 numbers in source are used:
1. numbered one
2. numbered two

1) numbered one
2 ) numbered two

i) roman numeral one
ii) roma numberal two		 # numbered one
# numbered two		 error if values in markup are not sequential starting from one:
1. numbered one
2. numbered two
definition list <dl>
<dd>one
<dt>the 1st cardinal
<dd>two
<dt>the 2nd cardinal
</dl>

pandoc extension; 4 spaces after colon:
one
:    the 1st cardinal
two
:    the 2nd cardinal		 one
  the 1st cardinal
two
  the 2nd cardinal		 ; one : the 1st cardinal
; two : the 2nd cardinal		 one::
  the 1st cardinal
two::
  the 2nd cardinal
block quote > Four score and twenty
> years ago…

pandoc also has lazy block quotes:

> Four score and twenty
years ago…

pandoc requires blank line before a block quote		 Main body text.

  Four score and twenty
  years ago…

More main body text.		 <blockquote>
Four score and twenty
years ago…
</blockquote>		 ****
Four score and twenty
years ago…
****		 #+BEGIN_QUOTE
Four score and twenty
years ago…
#+END_QUOTE
div w/ class <div class="foo">
markup
</div>		 <div class="foo">
markup
</div>
images
markdown restructured text mediawiki asciidoc org-mode
image
 		 <img src="foo.jpg"> .. image:: foo.jpg [[File:foo.jpg]] image:foo.jpg[] [[foo.jpg]]
image link <a href="http://foo.com">![](foo.jpg)</a> .. image:: foo.jpg
   :target: http://foo\.com		 [[File:foo.jpg|link=http://foo.com]] image:foo.jpg[link="http://foo.com"]
image with alt ![Foo](foo.jpg) .. image:: foo.jpg
   :alt: Foo		 [[File:foo.jpg|alt=Foo]] image:foo.jpg[Foo]
image size height can also be specified; height proportionate if not:
<img width="300px" src="foo.jpg">		 height can also be specified; height proportionate if not: _
.. image:: foo.jpg
   :width: 300px		 specify width; height will be proportionate:
[[File:foo.jpg|300px]]		 specify width; height will be proportionate:
image:foo.jpg[width="300px"]
tables, code, and math
markdown restructured text mediawiki asciidoc org-mode
table <table>
<tr><th>A<th>B
<tr><td>1<td>2
<tr><td>3<td>4
</table>

pandoc extensions:
A  B
-- --
1  2
3  4

pandoc extension:
+---+---+
| A | B |
+---+---+
| 1 | 2 |
+---+---+
| 3 | 4 |
+---+---+		 == ==
A  B
== ==
1  2
3  4
== ==

+---+---+
| A | B |
+===+===+
| 1 | 2 |
+---+---+
| 3 | 4 |
+---+---+		 {|border="1"
!A!!B
|-
|1||2
|-
|3||4
|}

one cell per row of markup:
{|border="1"
!A
!B
|-
|1
|2
|-
|3
|4
|}		 [width="20%", options="header"]
|===
|A|B
|1|2
|3|4
|===		 |A|B|
|-+-|
|1|2|
|3|4|
multiple column cell <table>
<tr><th colspan=2>title
<tr><td>1<td>2
</table>		 +-------+
| title |
+===+===+
| 1 | 2 |
+---+---+		 {|border="1"
!colspan="2"|title
|-
|1||2
|}		 [width="20%", options="header"]
|===
2+|title
|1|2
|===
cell alignment <table><tr>
<td align="left">left
<td align="center">center
<td align="right">right
</tr></table>		 {|border="1"
|align="left"|left
|align="center"|center
|align="right"|right
|}
pre-formatted fixed-width block with no need to escape markup or < and & set off from surrounding blocks with blank lines and indent each line at least 4 spaces:

    int add(int a, int b) {
      return (a+b);
    }
 

pandoc delimited code block uses 3 or more tildes or backticks:
~~~
int add(int a, int b) {
  return (a+b);
}
~~~		 If the preceding paragraph ends with two colons, it renders as a single colon. Two colons on a line by themselves are removed. Preformatted text is indented.
::

  int add(int a, int b) {
    return (a+b);
  }		 <pre>
int add(int a, int b) {
  return (a+b);
}
</pre>		 ----
int add(int a, int b) {
  return (a+b);
}
----		 #+BEGIN_EXAMPLE
int add(int a, int b) {
return (a+b);
}
#+END_EXAMPLE
highlighted code pandoc extension:
~~~c
int add(int a, int b) {
  return (a+b);
}
~~~		 Adds classes, but a style sheet is necessary to get the colors:
.. code-block:: c

  int add(int a, int b) {
    return (a+b);
  }		 <source lang=c>
int add(int a, int b) {
  return (a+b);
}
</source>		 source-hightlight must be installed:
[source,c]
----
int add(int a, int b) {
  return (a+b);
}
----
languages which can be highlighted lists the supported languages:
$ pandoc --version		 $ pygmentize -L lexers 100+ languages 150+ languages
latex math pandoc extension:

$ \int_0^\pi \cos (x) dx $		 .. math::

\int_0^\pi \cos (x) dx		 <math>\int_0^\pi \cos (x) dx</math>
________________ ______________________________________________ ___________________________________________ ___________________________________________ ___________________________________________ ___________________________________________

Markdown

Markdown

Markdown was developed in 2004, initially in Perl. It is used by Tumblr, Stackoverflow, GitHub, and Reddit. Here is a sandbox.

On Ubuntu you can install a script which converts Markdown to HTML with the following command:

sudo apt install markdown

The command line script converts Markdown to HTML. Invoke it like this:

$ markdown foo.md > foo.html

Pandoc

Pandoc User's Guide
Pandoc's Markdown

There are installers for Windows and Mac. On Ubuntu Pandoc can be installed with

sudo apt install pandoc

Pandoc can read Markdown, LaTeX, HTML, and a few other formats. It can output HTML, RTF, MediaWiki Syntax, groff man page format, Emacs Org-Mode, AsciiDoc, EPub, GNU Texinfo, Word docx, Slidy, and some other formats.

Pandoc's version of Markdown has extensions. Using the extensions avoids HTML and makes it easier for Pandoc to target other formats.

Converting Markdown to HTML:

$ pandoc foo.txt -o foo.html

Converting HTML to Markdown:

pandoc -s -r html http://hyperpolyglot.org/lightweight-markup -o lightweight-markup.txt

pdf from markdown

A tool such as pdflatex must be in the search path:

$ pandoc foo.txt -o foo.pdf

epub from markdown

$ pandoc foo.txt -o foo.epub

word document from markdown

$ pandoc foo.txt -o foo.docx

man page from markdown

groff_man(7) (ubuntu.com)

The markup used for man pages is described in groff_man(7).

$ cat > foo.1.md
% FOO(1) Foo User Manual
% John Smith
% November 8, 2012

# NAME

foo - a command line tool

# SYNOPSIS

foo [*file*]...

# DESCRIPTION

Foo performs an operation on files specified on the command line.  If no files
are specified the operation is performed on *stdin*.

# SEE ALSO

`bar` (1).

$ pandoc -s -w man foo.1.md -o foo.1

slideshow from markdown

$ cat > gnomes.txt
# Business Plan

* collect underpants
* ?
* profit

# Phase 1: Collect Underpants

3:30 AM is the optimal time.

# Phase 2: ?

Details TBD

# Phase 3: Profit

Financial results will be discussed in the earnings call.

$ pandoc gnomes.txt -s --webtex -i -t slidy -o gnomes.html

reStructuredText

reStructuredText Markup Specification

pydoc and rst2html5

$ sudo pip install sphinx

MediaWiki

MediaWiki Syntax

MediaWiki powers Wikipedia. The source code is freely available.

Wikipedia was launched in January 2001. The site initially used wiki software implemented in Perl called UseModWiki. In January 2002 the site switched to custom software written in PHP. The PHP code was rewritten for scalability in July 2002. It was given the name MediaWiki in 2003 and was eventually open sourced.

UseModWiki had a spare set of markup which did not expand much on the markup used by Wiki Base, the original wiki software used by WikiWikiWeb.

Wiki Base (1995) UseModWiki (1999) MediaWiki (2002) Markdown (2004)
link CamelCase CamelCase
[[Double Bracket]]		 [[Double Bracket]] [Single Bracket](url)
italic ''italic'' ''italic'' ''italic'' *italic*
bold '''bold''' '''bold''' '''bold''' **bold**
horizontal rule ---- ---- ---- ---
top level header none none =top level header= # top level header
second level header none none ==second level header== ## second level header
bullet list item * list item * list item * list item * list item
numbered list item none # list item # list item 1. list item
image can be URL:
foo.jpg		 can be URL:
foo.jpg		 [[File:foo.jpg]]
MediaWiki permits raw URL images
like its predecessors but the feature
is turned off on Wikipedia		 <img src="foo.jpg">
table none added in 2003:
||A||B||
||1||2||		 {|
!A!!B
|-
|1||2
|}		 <table>
<tr><td>A<td>B
<tr><td>1<td>2
</table>

For those who like to experiment, here are sandboxes for Wiki Base and UseModWiki.

In Wiki Base the way to prevent a camel case word from becoming a link was to insert six single quotes into the word like this: C''''''amelCase. The odd markup was not intentional. The six single quotes actually parse as a bold empty string.

UseModWiki had a feature called "free links" which was attractive to the founders of Wikipedia. It permitted page titles to have spaces, commas, periods, or hyphens in them. These pages could be linked with double brackets: e.g. [[Los Angeles]]. In the URL the spaces are replaced with underscores. UseModWiki is case insensitive but MediaWiki is case sensitive except for the first letter.

AsciiDoc

AsciiDoc User Guide
HTML Slidy: Slide Shows in HTML and XHTML

AsciiDoc can be installed by a variety of package managers. On Ubuntu:

sudo apt install asciidoc

On a Mac with MacPorts:

sudo port install asciidoc

AsciiDoc documents have a .txt suffix by default. The following command will create a file called foo.html:

$ asciidoc foo.txt

slideshow

$ asciidoc -b slidy foo.txt

Org-mode

The Org Manual

issue tracker | content of this page licensed under creative commons attribution-sharealike 3.0