Skip to content

Latest commit

 

History

History
491 lines (376 loc) · 6.97 KB

markup-comparison.adoc

File metadata and controls

491 lines (376 loc) · 6.97 KB

Markup Comparison

The goal of this document is to compare different markup languages. The comparison can be used to easily switch between the different languages. The document compares the unique features of the languages. There will be no documentation of special features only found in a single Markup.

For now the document covers the following markup languages:

For the Markdown language not only the standard syntax will be used. The document also references the GitHub Flavored Markdown syntax enhancements.

You are free to add more markup languages to this comparison.

Important
 This work is licensed under a Creative Commons Attribution 4.0 international license (CC-BY-SA 4.0).
Table of Contents

Document Structure

The structure of a document is made out of one or more sections. Section can be hierarchical. Often the initial section is treated as the title of the document.

Markdown AsciiDoc MediaWiki restructuredText 
# Level 1 Section

## Level 2 Section

### Level 3 Section
 
= Document Title
FirstName LastName <email>

== Level 1 Section

=== Level 2 Section

==== Level 3 Section
 
= Document Title =

== Level 1 Section ==

=== Level 2 Section ===

==== Level 3 Section ====
 
##############
Document Title
##############

***************
Level 1 section
***************

Level 2 section
===============

Level 3 section
---------------

Formatted Text

The languages use "special characters" to allow the formatting like bold, italic or monospace.

Markdown AsciiDoc MediaWiki restructuredText 
**bold**
__bold__
 
*bold*
 
'''bold'''
 
**bold**
 
*italic*
_italic_
 
_italic_
 
''italic''
 
*italic*
 
`monospace`
 
`monospace`
 
<tt>monospace</tt>
<code>monospace</code>
 
``monospace``

Unordered List

The format for unordered list are very similar. Nealry all languages allow more then one level for the list items.

Markdown AsciiDoc MediaWiki restructuredText 
* list item
* another list item
* and another list item

+ list item
+ another list item
+ and another list item

- list item
- another list item
- and another list item
 
* list item
* another list item
** list item in next level
* and another list item

- list item
- another list item
- and another list item
 
* list item
* another list item
** list item in next level
* and another list item
 
* list item
* another list item
  ** list item in next level
* and another list item

- list item
- another list item
- and another list item

Ordered List

The format for an ordered list are very similar. There is also the possibility to make a multi-level ordered list.

Markdown AsciiDoc MediaWiki 
1. first item
2. second item
3. third item

1. first item
1. second item
1. third item
 
. first item
. second item
.. first subitem of an item
. third item

[loweralpha]
. first item
. second item
. third item
 
* list item
* another list item
  * list item in next level
* and another list item

- list item
- another list item
- and another list item

Definition List

Markdown does not support definition lists. It’s possible to use direct HTML tags for that. All other languages support the definition list with their own syntax.

Markdown AsciiDoc MediaWiki restructuredText

n/a

 
label1:: Description of label1
label2:: Description of label2
label3:: Description of label3
 
:label1
: Description of label1
:label2
: Description of label2
:label3
: Description of label3
 
label1
  Description of label1

*label2*
  Description of label2

**label3**
  Description of label3

Links

Only links to external (URLs) are compared. Some languages also have the possibility to link to internal anchors or files.

Markdown AsciiDoc MediaWiki restructuredText 
This is a [link to Github](https://github.com/ "Title").
 
This is a https://github.com/[link to Github].
 
This is a [https://github.com/ link to Github].
 
This is a `link to Github <https://github.com/>`_.

Block Quotes

Block quotes are used to emphasize a paragraph. The text inside a block will be formatted like any other text.

Markdown AsciiDoc MediaWiki restructuredText 
> This ist a block
> quote.

> This is also an
block quote.
 
____
This is a block quote.
____
 
<blockquote>
This is a block quote.
</blockquote>
 
    This is a block quote.
        And this is another (nested) block quote.

Code Blocks

Code blocks are used to print out given text in the same format as entered. There will be no additional formatting of the text inside a code block.

Markdown AsciiDoc MediaWiki restructuredText 
    The code block is indented
    by at least 4 spaces
    or 1 tab.

```
The block can also be enclosed by fences `.
```
 
  The code block is indented
  by at least 2 spaces.
The block can also be
enclosed by 4 - or . chars.
 
<code>
This is a code block in MediaWiki.
</code>
 
::

  This is a code block in restructuredText.

Tables

Tables cannot be easily formatted with a markup language. The syntax of the different languages tries to build a kind of table drawing style.

Markdown AsciiDoc MediaWiki restructuredText 
Column 1 | Column 2
-------- | --------
Cell 1   | Cell 2
Cell 3   | Cell 4
 
|===
|Column1 |Column2

|Cell 1
|Cell 2

|Cell 3
|Cell 4

|===
 
{|
|Column1||Column2
|-
|Cell 1||Cell 2
|-
|Cell 3
|Cell 4
|}
 
+-----------+-----------+

Images

Depending on the markup languages images can be referenced with an absolute path. It’s also possible to reference pictures in a base dir. The format of the pictures must be supported by the used browser / viewer.

Markdown AsciiDoc MediaWiki restructuredText 
![alt text](/path/to/img.jpg)
 
image::img.jpg[alt text]
 
[[File:img.jpg||alt text]]

  1. image:: img.jpg :alt: alt text ---