Parsing, Rendering, and Converting Markdown in JavaScript: A Technical Deep-Dive

Most frontend and Node.js applications that surface user-authored content eventually confront the Markdown/HTML boundary: parse Markdown, render safe HTML, optionally enrich output (syntax highlighting, custom attributes), and sometimes move in the opposite direction when importing or round-tripping content from WYSIWYG editors. Markdown-it, Marked, Remark, Remarkable, and Showdown all render HTML from Markdown with different parsing models and extension hooks, while Turndown converts HTML back to Markdown using DOM rules.

Design Philosophy

• markdown-it: Tokenizer + renderer architecture with rule-level hooks. Aims at CommonMark compatibility and predictable rendering with opt-in extras. Emphasizes a plugin ecosystem for syntax extensions and renderer tweaks.
• marked: A pragmatic renderer with GFM support and a concise extension API. Customization is done via renderer overrides, tokenizers, and token walking rather than an AST-first workflow.
• remark: AST-first (mdast) via the unified pipeline. Markdown is parsed into a typed tree, then transformed and compiled (commonly to HTML via rehype). This favors complex transformations, content validation, and multi-target outputs.
• remarkable: Similar surface area to markdown-it with renderer rules and a highlight hook. Simpler ecosystem and fewer moving parts.
• showdown: Configuration-first with extension hooks. Less formal parsing model; trades strictness for convenience and broad compatibility with Markdown variants.
• turndown: HTML-to-Markdown, not a renderer. Rule-based DOM traversal where each rule declares filter(s) and string replacements, enabling lossy or lossless mappings depending on your rules.

Parsing Model and Extensibility

• Token streams (markdown-it, remarkable): Expose block/inline rules and renderer rules. You can inject attributes into specific tokens, alter nesting behavior, or add new syntaxes with plugins.
• Tokenizers without a formal AST (marked): Offers tokenization with hooks. You can extend parsing via custom tokenizers and adjust output via a renderer object; walkTokens enables post-parse analysis.
• AST-first (remark): remark-parse builds mdast; remark plugins transform that AST; remark-rehype converts to HAST; rehype plugins transform HTML AST; rehype-stringify emits HTML. The pipeline decomposes concerns and allows sophisticated invariants.
• Regex/config-first (showdown): Options cover many behaviors; extensions can manipulate input or output with filter functions. Less structure than token/AST pipelines, but straightforward for light customization.
• DOM rule-based (turndown): Each rule declares how to match HTML nodes (by tag, predicate) and how to produce Markdown. Reliable for controlled HTML; complex inputs may require multiple rules to avoid lossy conversion.

HTML Handling and Security Posture

• None of the Markdown→HTML libraries sanitize by default in a security-hard sense. markdown-it and remarkable can disallow raw HTML entirely (html: false), but that’s not equivalent to sanitization. marked previously exposed sanitize-related options historically but now expects external sanitization (e.g., DOMPurify in browsers, or a server-side sanitizer). Showdown includes a sanitize toggle that strips HTML but is coarse and not a full sanitizer.
• remark pipelines typically use rehype-sanitize, a configurable HTML AST sanitizer. This is the most programmable approach when you need to allow a controlled subset of HTML.
• For browser contexts, DOMPurify remains a common final step regardless of parser if you allow raw HTML at any point.

Edge Cases and Spec Nuance

• CommonMark and GFM: remark requires remark-gfm to support tables/strikethrough/task lists. marked supports GFM features behind options. markdown-it supports CommonMark and common GFM constructs, and its ecosystem covers the rest. remarkable and showdown handle many GFM-like features, but behaviors can diverge on corner cases (e.g., nested emphasis, list tight/loose spacing).
• Autolink literals (bare URLs): markdown-it can auto-link with linkify: true. marked focuses on Markdown-specified links; autolinking bare URLs may require an extension/preprocess. remark can add autolinks with a plugin at either mdast or hast stage. showdown offers simplified autolink options that may link common URL patterns.
• Raw HTML passthrough: markdown-it/remarkable can allow or block raw HTML. marked passes it through by default. For remark, raw HTML requires allowing it through remark-rehype plus rehype-raw and then sanitizing.

Performance Characteristics

• Direct renderers (marked, markdown-it, remarkable) usually have lower overhead for “Markdown→HTML now” without AST transforms. They’re a good fit when you don’t need deep analysis or restructuring.
• remark’s AST pipeline adds overhead but unlocks structured transformations, linting, and precise HTML control. In content-heavy builds (SSG/CMS), the clarity of transformations often offsets runtime cost.
• showdown’s looser parsing and extension filters are simple to wire but can be less predictable on pathological inputs. turndown processes DOMs; cost scales with tree size and the complexity of your rules.

Output Control and Customization

• markdown-it/remarkable: Customize via renderer.rules; add/remove attributes per token; implement syntax highlighting with a highlight callback.
• marked: Customize via a Renderer instance or marked.use; walkTokens supports cross-cutting transformations. Highlighting is injected via a highlight option.
• remark: Insert transformations where they make the most sense—mdast (structure), during mdast→hast (representation), or in HAST (HTML-specific policies like rel/target). Highlighting is typically handled with rehype plugins.
• showdown: Configure via options; add small output filters as extensions. More brute-force than structural.
• turndown: Precisely control Markdown output by authoring rules for tags or predicates; use it to preserve language hints for fenced code or normalize links/strong/emphasis the way you want.

The Same Task, Implemented Across Libraries

Goal: Convert a Markdown snippet to HTML with syntax highlighting and external links opening in a new tab with rel attributes. For Turndown (HTML→Markdown), perform the equivalent customization when converting the produced HTML back to Markdown by preserving fenced code language and normalizing links.

Sample Input Markdown

# Demo

Visit https://example.com and [MDN](https://developer.mozilla.org/).

```js
console.log('hi')

### markdown-it
```js
import MarkdownIt from 'markdown-it';
import prism from 'prismjs';

const md = new MarkdownIt({
  html: false,
  linkify: true,
  highlight: (code, lang) => {
    try {
      const grammar = prism.languages[lang] || prism.languages.markup;
      const highlighted = prism.highlight(code, grammar, lang);
      return `<pre class="language-${lang}"><code class="language-${lang}">${highlighted}</code></pre>`;
    } catch {
      return `<pre><code>${md.utils.escapeHtml(code)}</code></pre>`;
    }
  }
});

const defaultOpen = md.renderer.rules.link_open || ((tokens, idx, options, env, self) => self.renderToken(tokens, idx, options));
md.renderer.rules.link_open = (tokens, idx, options, env, self) => {
  tokens[idx].attrSet('target', '_blank');
  tokens[idx].attrSet('rel', 'noopener noreferrer');
  return defaultOpen(tokens, idx, options, env, self);
};

const html = md.render(markdown);

Notes: linkify makes bare URLs clickable; raw HTML is disabled. Add a sanitizer for untrusted input if you enable raw HTML.

marked

import { marked } from 'marked';
import prism from 'prismjs';

const renderer = new marked.Renderer();
renderer.link = (href, title, text) => {
  const t = title ? ` title="${title}"` : '';
  return `<a href="${href}"${t} target="_blank" rel="noopener noreferrer">${text}</a>`;
};

marked.setOptions({
  gfm: true,
  highlight: (code, lang) => {
    const grammar = prism.languages[lang] || prism.languages.markup;
    return prism.highlight(code, grammar, lang);
  }
});

const html = marked.parse(markdown, { renderer });

Notes: bare URLs may not auto-link without an extension/preprocess. Pair with a sanitizer when rendering untrusted Markdown.

remark (unified + rehype)

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkGfm from 'remark-gfm';
import remarkRehype from 'remark-rehype';
import rehypeExternalLinks from 'rehype-external-links';
import rehypeHighlight from 'rehype-highlight';
import rehypeStringify from 'rehype-stringify';

const file = await unified()
  .use(remarkParse)
  .use(remarkGfm)
  .use(remarkRehype, { allowDangerousHtml: false })
  .use(rehypeExternalLinks, { target: '_blank', rel: ['noopener', 'noreferrer'] })
  .use(rehypeHighlight)
  .use(rehypeStringify)
  .process(markdown);

const html = String(file);

Notes: rehype-external-links centralizes link policy; highlighting is pluggable; add rehype-sanitize if allowing raw HTML.

remarkable

import Remarkable from 'remarkable';
import prism from 'prismjs';

const md = new Remarkable('full', {
  html: false,
  linkify: true,
  highlight: (code, lang) => {
    try {
      const grammar = prism.languages[lang] || prism.languages.markup;
      const highlighted = prism.highlight(code, grammar, lang);
      return `<pre class="language-${lang}"><code class="language-${lang}">${highlighted}</code></pre>`;
    } catch {
      return '';
    }
  }
});

const defaultOpen = md.renderer.rules.link_open || ((tokens, idx, options, env, self) => self.renderToken(tokens, idx, options));
md.renderer.rules.link_open = (tokens, idx, options, env, self) => {
  tokens[idx].attrSet('target', '_blank');
  tokens[idx].attrSet('rel', 'noopener noreferrer');
  return defaultOpen(tokens, idx, options, env, self);
};

const html = md.render(markdown);

Notes: control is similar to markdown-it with renderer rules and a highlight hook.

showdown

import showdown from 'showdown';

const converter = new showdown.Converter({
  tables: true,
  strikethrough: true,
  openLinksInNewWindow: true,
  ghCodeBlocks: true
});

// Add rel attributes to links post-render
converter.addExtension(function() {
  return [{
    type: 'output',
    filter: (html) => html.replace(/<a\s+href=/g, '<a rel="noopener noreferrer" href=')
  }];
}, 'relNoopener');

const html = converter.makeHtml(markdown);

Notes: extensions operate on strings; autolinking bare URLs depends on options and may be less strict; add a sanitizer externally for untrusted content.

turndown (HTML→Markdown with equivalent customizations)

import TurndownService from 'turndown';

const turndown = new TurndownService({ codeBlockStyle: 'fenced' });

// Preserve language info from <pre><code class="language-...">
turndown.addRule('fencedCodeWithLang', {
  filter: (node) => node.nodeName === 'PRE' && node.firstChild && node.firstChild.nodeName === 'CODE',
  replacement: (content, node) => {
    const codeEl = node.firstChild;
    const cls = codeEl.getAttribute('class') || '';
    const match = cls.match(/language-([\w-]+)/);
    const lang = match ? match[1] : '';
    const code = codeEl.textContent || '';
    return `\n\`\`\`${lang}\n${code}\n\`\`\`\n`;
  }
});

// Normalize links (ignore target/rel attributes in Markdown)
turndown.addRule('normalizeLinks', {
  filter: 'a',
  replacement: (content, node) => {
    const href = node.getAttribute('href') || '';
    const title = node.getAttribute('title');
    const t = title ? ` "${title}"` : '';
    return href ? `[${content}](${href}${t})` : content;
  }
});

const markdownOut = turndown.turndown(html /* HTML produced by any renderer above */);

Notes: turndown operates on DOM nodes, making it reliable for controlled HTML. Complex interactive HTML may need additional rules to avoid lossy mappings.

Observable Differences in Output

• Link attributes: markdown-it/remarkable provide token-level hooks; marked centralizes link rendering via renderer.link; remark delegates to rehype, enabling site-wide policies with a single plugin; showdown needs an output filter.
• Code highlighting: markdown-it/remarkable/marked accept a highlight function; remark integrates via rehype plugins; showdown typically relies on post-processing or output filters; turndown preserves language by inspecting class names.
• Tables: remark requires remark-gfm; marked supports GFM tables with gfm enabled; markdown-it/remarkable parse common table syntax; showdown requires tables: true. Output HTML structure (thead/tbody alignment classes) varies—CSS hooks differ by library.
• Bare URLs: markdown-it linkify auto-links; remark can add a plugin; marked and showdown may need opt-in or preprocessing.

Failure Modes and Limitations

• Sanitization is not built-in at a security-hard level for renderers; failing to add a sanitizer can expose XSS if raw HTML is allowed.
• Regex/string extensions (showdown) are easy to write but can break on nested or malformed HTML; prefer structural hooks when correctness is critical.
• Deep structural rewrites (e.g., rewrite heading hierarchy, generate slugs, build TOCs) are far easier with remark’s AST pipeline than with token/regex-based systems.
• Round-tripping is lossy by nature unless both directions agree on conventions. turndown mitigates this with targeted rules but complex interactive HTML or custom widgets won’t map cleanly to Markdown.

Synthesis

Each library reflects a different assumption about how Markdown should flow through your system. Token/renderer pipelines (markdown-it, remarkable) prioritize predictable rendering with precise, small surface-area hooks. marked optimizes for a pragmatic, minimal-ceremony path to GFM HTML with extension points that cover most customization needs. remark treats content as data—parse to a typed tree, transform deliberately, and compile with explicit sanitization and HTML policies. showdown favors quick wins with options and string-level extensions. turndown completes the picture by enabling HTML→Markdown ingestion, codifying reversal rules when the source of truth lives in HTML rather than Markdown.