Markdown-it Insert Text Plugin

4.0.0 · active · verified Tue Apr 21

markdown-it-ins is a plugin for the popular markdown-it parser that extends its functionality to include support for the HTML `<ins>` (inserted text) tag. It allows users to mark text for insertion using the `++text++` syntax, mirroring the behavior of CommonMark's emphasis rules. The current stable version is 4.0.0, published approximately two years ago, which implies a release cadence tied to upstream `markdown-it` updates or specific feature additions. A key differentiator is its focused purpose: providing `<ins>` tag support specifically for the markdown-it ecosystem, offering a straightforward way to add this semantic markup. While markdown-it itself is highly configurable and extensible, this plugin provides a ready-to-use solution for this specific text-level semantic element without requiring custom rule implementations.

Common errors

```
`md.use is not a function` or `Cannot read property 'use' of undefined`
```
cause The `markdown-it` instance was not correctly initialized or the `markdown-it-ins` plugin was not properly imported. In CommonJS, `require('markdown-it')` is the function, not a default export.

fix Ensure `markdownit` is initialized as `const md = require('markdown-it')();` (CommonJS) or `import markdownit from 'markdown-it'; const md = markdownit();` (ESM). Then pass `require('markdown-it-ins')` or `markdownitIns` to `md.use()`.
```
Error: Plugin 'markdown-it-ins' cannot be used with markdown-it version X.Y.Z (expected >=10.0.0)
```
cause Using `markdown-it-ins` version 3.0.0 or higher with an incompatible older version of `markdown-it` (e.g., `<10.0.0`).

fix Upgrade your `markdown-it` package to version 10.0.0 or newer. In `package.json`, set `"markdown-it": "^10.0.0"` (or higher) and run `npm install`.
```
++text++ is rendered as plain text, not HTML <ins> tags
```
cause The `markdown-it-ins` plugin was either not correctly `use()`d with the `markdown-it` instance, or there's a conflict with another plugin/rule that processes the `++` syntax before `markdown-it-ins` can.

fix Verify that `md.use(markdownitIns)` is called after `markdownit` initialization. Check the order of plugins if multiple are used, as some may interfere with others' parsing rules. Ensure no custom `markdown-it` rules are inadvertently disabling or overriding the plugin's functionality.

Warnings

breaking Version 3.0.0 and above of `markdown-it-ins` require `markdown-it` version 10.0.0 or higher. Using older versions of `markdown-it` with `markdown-it-ins` v3+ will lead to runtime errors or incorrect parsing due to internal API changes in `markdown-it`.
Fix: Ensure your `markdown-it` dependency is at `^10.0.0` or higher. For npm, update `package.json` to `"markdown-it": "^10.0.0"` and run `npm install`.
gotcha While `markdown-it-ins` handles `++text++` markup, `markdown-it` itself can be vulnerable to various security issues like XSS, ReDoS, or infinite loops if not updated or if parsing untrusted input. These vulnerabilities are in the core parser, not the plugin, but can affect the overall application security.
Fix: Always keep `markdown-it` updated to its latest stable version (currently `^13.0.0`). Sanitize all user-submitted markdown content, especially if `html: true` is enabled in `markdown-it` options, to prevent XSS.
gotcha The `++text++` markup for `<ins>` follows CommonMark emphasis rules. This means nested `++` or specific character sequences might behave unexpectedly if not properly escaped or understood in the context of markdown parsing. For example, `++foo++bar++baz++` might not produce the desired nested `<ins>` tags.
Fix: Consult the CommonMark specification for emphasis rules. If complex nesting or specific character handling is required, pre-process the markdown or use a more robust parser for such edge cases. Escaping with `\` might be necessary for literal `++` characters.

Install

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

Imports

markdownitIns
wrong:
```
import { markdownitIns } from 'markdown-it-ins';
```
correct:
```
import markdownit from 'markdown-it';
import markdownitIns from 'markdown-it-ins';

const md = markdownit().use(markdownitIns);
```
The `markdown-it-ins` plugin is typically imported as a default export in ESM contexts and passed directly to `markdown-it`'s `.use()` method. `markdown-it` itself also supports ESM imports for `markdownit` as of recent versions.
require('markdown-it-ins')
wrong:
```
const markdownitIns = require('markdown-it-ins').default;
```
correct:
```
const markdownit = require('markdown-it');
const markdownitIns = require('markdown-it-ins');

const md = markdownit().use(markdownitIns);
```
For CommonJS environments, `require('markdown-it-ins')` directly returns the plugin function. Similarly, `markdown-it` is required directly. This is the pattern shown in the official README.
window.markdownitIns
```

<script>
  const md = window.markdownit();
  md.use(window.markdownitIns);
  console.log(md.render('++inserted++'));
</script>
```
When loaded directly in a browser without a package system, the plugin attaches itself globally as `window.markdownitIns`. `markdown-it` itself also exposes `window.markdownit`.

Quickstart

Demonstrates how to import and register `markdown-it-ins` with `markdown-it` to process `++text++` markup into `<ins>` HTML tags.

import markdownit from 'markdown-it';
import markdownitIns from 'markdown-it-ins';

// Initialize markdown-it with the ins plugin
const md = markdownit().use(markdownitIns);

// Example usage with ++inserted++ syntax
const markdownText = `Hello, ++this text should be inserted++.\n\nThis is a paragraph with ++another inserted phrase++ and a regular sentence.`;

const htmlOutput = md.render(markdownText);

console.log('Markdown Input:\n', markdownText);
console.log('\nHTML Output:\n', htmlOutput);

// Expected output: <p>Hello, <ins>this text should be inserted</ins>.</p><p>This is a paragraph with <ins>another inserted phrase</ins> and a regular sentence.</p>

view raw JSON →