Lightweight markup language for a Website

By Dec 27, 2017


Here we compare Markdown and ReStructuredText and discuss their integration into content managers.


In recent years, we have witnessed the development of CMS, generators of blogs and generators of static sites. These allow people who have virtually nothing to do with building a website, manage their own site and easily add content.

To add content, you insert solid text, pure HTML, or formatted code into a lightweight markup language (usually Markdown).
On the other hand, one can often regret the absence of a good HTML editor embedded WYSIWYG. This would allow the text to be formatted according to a given style sheet. Moreover it is not very convenient to type code in a simple text editor and it requires to learn the HTML language.
There is still the ability to type text in a lightweight markup language such as Markdown or reStructuredText that convert text to HTML in a certain style.
But these languages that are intended to be simple and as readable as possible by the human, require an apprenticeship of a few rules and are not always installed by default in the content generators.

Markdown, reStructuredText

There are a multitude of lightweight markup languages, but currently the most popular are Markdown and ReStructuredText with a clear advantage for Markdown. We will not talk about others who have too restrictive  license which may prevent their commercial use or those whose syntax is too complicated.
Markdown and reStructuredText can both transform plain text into HTML or XHTML and are now both used to write technical documentation.
But unlike reStructuredText, Markdown allows inline HTML. On the other hand reStructuredText is a more extensible language.

A disadvantage of Markdown is that it has several implementations that do not have exactly the same specifications. Clarification efforts have led to the creation of a new dialect called CommonMark. CommonMark adds the following specifications to Markdown:

  • Markdown inside HTML blocks
  • Elements with id or class attribute
  • Fenced code blocks
  • Tables
  • Definition lists
  • Footnotes
  • Abbreviations
But Markdown remains the most used in Web development. An important advantage of Markdown on reStructuredText is that there are HTML viewers that can instantly show the result of converting to HTML.
  Markdown/CommonMark reStructuredText
link offsite [Website](
or [Link][1]


`Website <>`_


link onsite <a href="page">Link</a>


link with url in footnote    
define anchor <a name="anchor"/> .. _anchor:
link to anchor <a href="#anchor">Anchor</a> anchor_
  Markdown/CommonMark reStructuredText
italic text
Emphasised text
*italic text*
or _italic text_

italic text

*italic text*
or :emphasis:`italic text`

italic text

bold text **bold text**
or __bold text__

bold text

**bold text**
or :strong:`bold text`

bold text

literal text   ``literal text``
:literal:`literal text`

literal text

strong emphasised text ***strong emp text***

strong?emp text

**strong emp text**
or :strong:`strong emp text`

strong?emp text

small caps text  
fixed width text
inline code `inline code`

inline code

 :code:`inline code`

inline code

underlined text    
striketrhough text <del>strikethough text</del>

strikethough text

superscript text<sup>superscript</sup>


text\ :sup:`superscript`


subscript text<sub>subscript</sub>


text\ :sub:`subscript`


  Markdown/CommonMark reStructuredText
section header # section header
section header
section header
subsubsection header ## subsection header
subsection header
subsection header
subsubsection header ## subsubsection header
subsubsection header
subsubsubsection header ### subsubsection header
subsubsubsection header
  Markdown/CommonMark reStructuredText
line break a backslash at the end of the line
or two spaces at the end of line
| text
| newline
horizontal rule ***

list item * item1
* item2
- item1

- item2
numbered list item 1. numbered item1
2. numbered item2

1) numbered item1
2) numbered item2

i. roman numeral 1
ii. roman numeral 2
1. numbered item1
2. numbered item2

1) numbered item1
2) numbered item2

i) roman numeral 1
ii) roman numeral 2
definition list one
  1st item
  2nd item
block quote
  Markdown/CommonMark reStructuredText
image <img src="foo.png"> .. image:: foo.png
image link <a href="">![](foo.png)</a> .. image:: foo.png
:target: http://website\.com
image with alt ![AnImage](foo.png) .. image:: foo.png
:alt: AnImage
image with size <img width="350px" src="foo.png"> .. image:: foo.png
:width: 350px
  Markdown/CommonMark reStructuredText
table <table>
== ==
A   B
== ==
1  10
2  20
== ==
multiple column cell <table>
<tr><th colspan=2>AB</th></tr>
|   AB  |
| 1 | 2 |
cell alignment <table><tr>
<td style="text-align: left">left</td>
<td style="text-align: center">center</td>
<td style="text-align: right">right</td>
left      center     right

If you don't know which one to choose, look at the quality of the generated HTML code as well as the compatibility with HTML5 and especially the availability of these languages on your work platform. Plus if you need to integrate it yourself into your content management system, try to determine which one will install most easily. It is rare that it is not necessary to modify the resulting HTML code with a script to correct some imperfections, or to integrate Bootstrap etc.

Disadvantages of Lightweight markup languages

Even if the text is encoded in UTF-8, they generally do not support all languages (such as RTL languages) and do not allow to represent a multilingual text properly.

They do not allow to structure the text easily. For example, it will be quite complicated to create three columns and distribute the text in these three columns.

The fact that there are writing conventions makes collaborative work more difficult especially with people who know nothing about these languages.

Web Programming