Firstly it is worth noting that Markdown is simple, ubiquitous and integrated into many systems. This is a big pro - if Markdown is sufficient for your needs then there is really no need to look any further.

We wanted something that is as easy to read and write in source form as markdown but with more functionality and structure. This is why we created quantum.

If you are still interested to find out when and where you might want to use quantum over markdown then please, read on!

Markdown has a fixed way of rendering the markup to HTML (although there are several different flavours). In this respect it isn't at all customisable. This is actually one of the strengths of markdown - it has a small set of features and focused way of doing things that makes it really easy to pick up and use.

Quantum is build with customisability in mind - every part of the rendering process can be customised, allowing new functionalty to easily be added. New renderers that convert entites to html are easy to define and override in quantum. In quantum you choose how your markup gets converted into HTML. This can be achieved by picking libraries of transforms that already meet your needs, or by rolling your own transforms.

This highlights difference in opinion between the two markup languages - in Quantum everything is tagged with a type, and each type can be rendered to HTML in whatever way you want. In markdown the markup is tightly tied with HTML tags.

Whilst Markdown provides nice markup for a subset of HTML, is not a full HTML preprocessor replacement.

Quantum can be used as a full HTML preprocessor - with the use of the quantum-html module

Quantum has the same syntax when doing HTML preprocessing, as when using more high level entites. With markdown, html can be used directly when markdown doesn't have syntax for the tag you need.

An example of quantum being used to do HTML preprocessing:

There isn't really an equivelent snippet for markdown in this case, as markdown is not designed for this use.

Markdown puts a heavy focus on the source being as human readable as the rendered HTML page. It's kind of its thing.

Quantum has a similar focus, but also tries to ensure that working with the parsed content is easy. Having tagged entities makes this possible but does add some verbosity to the source. Compare the following two:

Markdown uses symbols to keep the markup from interfering with the readability of the source.

Quantum uses more explicit names for things, which adds flexibilty and explicitness, at the expense of some verbosity.

Things like, injecting variables when building your site so that it uses different config when vs in production If statements, loops, defining common blocks of markup for reuse elsewhere, etc

Markdown doesn't support templating out of the box, but is added by many markdown-based static site generators.

Quantum can do templating when the quantum-template module is included in the pipeline.

This section shows roughly equivalent ways of doing things in Markdown and Quantum. This section only compares things that Markdown and Quantum have in common.

Type	Markup	Result
Bold Text	Markdown Some **bold** text Quantum Some @bold[bold] text	Some bold text
Italic Text	Markdown Some _italic_ text Quantum Some @italic[italic] text	Some italic text
Strikethrough Text	Markdown Some ~~crossed out~~ text Quantum Some @strikethrough[crossed out] text	Some crossed out text
Headers	Markdown # H1 ## H2 ### H3 #### H4 ##### H5 ###### H6 Quantum @h1: H1 @h2: H2 @h3: H3 @h4: H4 @h5: H5 @h6: H6	H1 H2 H3 H4 H5 H6
Code highlighting	Markdown ``` function () { return 0; } ``` Quantum @codeblock js function () { return 0; }	function () { return 0; }
Inline code highlighting	Markdown Some `inline()` code Quantum Some @code[inline()] code	Some inline() code
Links	Markdown Click [here](/path/to/link). Quantum Click @hyperlink(/path/to/link)[here].	Click here
Lists	Markdown - item 1 - item 2 - item 3 1. item 2. item 3. item Quantum @list @item: item 1 @item: item 2 @item: item 3 @list ordered @item: item @item: item @item: item	item 1 item 2 item 3 item 1 item 2 item 3
Images	Markdown  Quantum @image(/quantumjs/resources/logo.png)[Quantum Logo]