Marquis

Marquis is a fast, regex-based Markdown to HTML conversion engine. It is both lightweight and offers additional features such as basic input sanitization. Recognizes all basic markdown syntax with extended syntax in development.

Visit the Demo to see what Marquis can do...

Performance Benchmarks

Testing was done using various files both with and without Markdown syntax being utilized. Each file was tested 15 times on each implementation with the 5 fastest being used to calculate the average which is shown in the results below.

Markdown Documentation - Syntax.text | Implementation | Time | | ------ | ------ | | Marquis 🥇 | 3.35 ms | | markdown-it | 10.40 ms | | Marked | 14.07 ms | | Showdown | 18.37 ms |

The Canterbury Corpus - Alice29.txt | Implementation | Time | | ------ | ------ | | Marquis 🥇 | 8.06 ms | | markdown-it | 17.92 ms | | Marked | 18.68 ms | | Showdown | 47.16 ms |

The Large Corpus - bible | Implementation | Time | | ------ | ------ | | markdown-it | 79.78 ms | | Marked | 88.69 ms | | Marquis 🥉 | 150.25 ms | | Showdown | 258.83 ms |

Installation

$ npm i marquisjs

Usage

Importing

import { marquis } from 'marquisjs'

Converting

const markdownText = `# Header 1`
const formattedBody = await marquis(markdownText);

Output

> console.log(formattedBody)

<pre class="marquis__body" style="white-space:pre-wrap;">
<h1>Header 1</h1>
</pre>

Styling

The HTML generated is wrapped in a <pre> tag with class marquis__body. It also by default styled with white-space: pre-wrap. By default <pre> will typically use monospace font. To change this along with any other styles simply add to your stylesheet.

Example:

.marquis__body {
    font-family: "Inter"
}

Notes

When using Marquis, there are a few things to note.

Wrapping with <pre>

The decision to wrap the generated HTML in a <pre> tag came from a desire to have the output match the desired intention of the input. In other markdown implementations <p> tags are utilized to contain lines of text seperated by 2 or more linebreaks. If a user wants 3 linebreaks in a row they have to resort to hacky methods to accomplish this. I think Markdown can be such a valuable tool for so many applications, so removing any barrier to entrance was a priority. Wrapping the generated HTML in a <pre> tag is unorthodox, but I found for the everyday user this will better reflect their intentions.

Lists

Lists in Marquis are stricter than other implementations. The regex used to match a list is:

/(?<=^ +(\d\.|\*|\+|-) +.*$(\n+)|)^( +)(\d\.|\*|\+|-)( +.*)$(\n*)(?=( +)(\d\.|\*|\+|-) |)/gm

This regex is capable of detecting both ordered and unordered lists as well as depth. Marquis requires at least one space before the list marker (*, +, -, n. ). The motivation behind this is that a user should be deliberate in starting a list. In other markdown implementations a list will be detected if an asterisk is simply the first character in a line. I find this approach to be flawed as it concerns intentionality. If one wanted to put an asterisk at the start of a newline, they would have to escape it with a backslash in most implementations. I believe utilizing Markdown syntax should be the deliberate act, not the inputting of plain text. By requiring a space before the marker, the act of intentionality is rightfully passed from the inputting of plaintext to the Markdown syntax.

The next point of interest is how Marquis handles nested lists. Orders of depth are defined by 4 spaces. This means you can have arbitrary levels of depth without requiring all the previous levels of depth. Example:

 * 1_1
         * 3_1
     * 2_1
         * 3_2
 * 1_2

Version History

Marquis 1.0.0

Features:

• Recognition of the following markdown syntax:
  • Headings
    • '#' and '='/'-' underlining
  • Emphasis
    • Italic '*text*' and '_test_'
    • Bold '**text**' and '__text__'
  • Strikethrough
    • '~~text~~'
  • Code
    • Inline '`text`'
    • Block '```text```'
  • Lists
    • Ordered ' n. text'
    • Unordered ' * text' | ' - text' | ' + text'
  • Links
    • '[link text](url)
  • Images
    • '
  • Horizontal Rules
    • '---' and '___'
  • Escaped Characters
    • '\character'
• Basic Input sanitization

Missing Features:

• Does not recognize the following markdown syntax:
  • Tables
  • Footnotes
  • Definition Lists
  • Task Lists
  • Emoji
  • Highlight
  • Subscript
  • Superscript