Markdown-it Parser

Common errors

• TypeError: markdownit is not a constructor

  cause Attempting to `import { markdownit } from 'markdown-it'` (named import) instead of `import markdownit from 'markdown-it'` (default import) in an ESM environment, or mixing CJS `require` with an ESM-only context.
  fix Use `import markdownit from 'markdown-it'` for ESM or `const markdownit = require('markdown-it')` for CommonJS.

• ReferenceError: markdownit is not defined

  cause In a browser environment, the `markdown-it` UMD build exposes its API on `window.markdownit`. Directly using `markdownit()` without `window.` will result in this error.
  fix Ensure you are referencing `window.markdownit()` when using the UMD build directly in the browser.

• My custom plugin isn't working or is conflicting with existing rules.

  cause Incorrectly registered the plugin, specified a wrong rule name, or set an incorrect rule priority, leading to it not firing or being overridden.
  fix Verify plugin registration (`md.use(plugin)`). Check rule names for typos. Adjust rule insertion methods (`.before()`, `.after()`, `.at()`) and priorities to ensure correct execution order.

Warnings

• gotcha When using markdown-it in a browser environment via a `<script>` tag, the global variable created is `window.markdownit` (without a hyphen). Attempting to access `window.markdown-it` will result in a `ReferenceError`.
  Fix: Access the global instance using `window.markdownit`.
• breaking Earlier versions of markdown-it (prior to v11) had a different default preset. If you are upgrading from a very old version, some default rules or options may have changed, potentially altering rendering output.
  Fix: Explicitly initialize with a preset (e.g., `markdownit('default')`) or configure options to match previous behavior after consulting the changelog for your specific upgrade path.
• gotcha While markdown-it is designed to be safe by default, using third-party plugins can introduce security vulnerabilities if they are not properly audited. Always review plugin code for potential XSS or other injection risks, especially if processing untrusted user input.
  Fix: Only use well-vetted and trusted plugins from reliable sources. When in doubt, audit plugin code or sanitize the output further if it contains user-generated content after parsing.
• gotcha Managing rule priorities and order when adding or replacing custom parsing rules can be complex. Incorrect rule configuration can lead to unexpected parsing behavior or conflicts between rules.
  Fix: Thoroughly test custom rule sets with diverse Markdown inputs. Consult the 'Development info' documentation on the GitHub repository for guidance on rule management and plugin development.

Install

• npm install markdown-it npm
• yarn add markdown-it yarn
• pnpm add markdown-it pnpm

Imports

• markdownit
  wrong:

  import { markdownit } from 'markdown-it'

  correct:

  import markdownit from 'markdown-it'

  Primary ESM import for Node.js and modern browser bundlers. It's a default export.
• markdownit

  const markdownit = require('markdown-it')

  CommonJS import for Node.js environments. This is the traditional way for older projects.
• MarkdownIt

  import type MarkdownIt from 'markdown-it'

  For TypeScript users to import the type definition of the default export.
• window.markdownit

  const md = window.markdownit()

  For browser environments loading markdown-it via a <script> tag (UMD build). Note the global is `markdownit` (no dash).

Quickstart

Demonstrates basic markdown-it initialization with common options, renders a block of Markdown text, and shows inline rendering for single-line content.

import markdownit from 'markdown-it';

// Initialize markdown-it with specific options
const md = markdownit({
  html: true,        // Enable HTML tags in source
  linkify: true,     // Autoconvert URL-like text to links
  typographer: true  // Enable smart quotes and other typographic replacements
});

// Example 1: Basic rendering
const markdownText1 = '# Hello, markdown-it!\n\nThis is a *simple* paragraph with an [example link](https://example.com).';
const htmlResult1 = md.render(markdownText1);
console.log('Basic Render:\n', htmlResult1);

// Example 2: Render inline content (without paragraph wrap)
const markdownText2 = '__markdown-it__ rulezz!';
const htmlResult2 = md.renderInline(markdownText2);
console.log('\nInline Render:\n', htmlResult2);

// Example 3: Demonstrating typographer and linkify
const markdownText3 = 'Check out google.com or write "hello" here.';
const htmlResult3 = md.render(markdownText3);
console.log('\nTypographer & Linkify:\n', htmlResult3);