remark-disable-text-escape

A remark plugin to prevent special characters from being escaped by remark-stringify.

Problem

By default, remark-stringify escapes special characters in text nodes (e.g., [ → \[, * → \*, _ → \_, ( → \(, @ → \@) to avoid ambiguity with Markdown syntax. This can be undesirable when you want to preserve these characters as-is in your Markdown output (e.g., **強調** becoming \*\*強調\*\* or foo_bar_baz becoming foo\_bar\_baz).

Additionally:

• Parentheses and ampersands in link/image URLs are escaped (e.g., [text](url(x)) → [text](url\(x\)), [text](a&b) → [text](a\&b))
• Autolinks containing special characters lose their format (e.g., <http://a_b.com> → [http://a_b.com](http://a_b.com))
• When used with remark-wiki-link, underscores in WikiLinks are escaped (e.g., [[page_name]] → [[page\_name]])

How it works

This plugin works in three ways:

1. Custom Node Pattern — transforms special characters in text nodes into custom literalChar AST nodes with a dedicated serialization handler. Since mdast-util-to-markdown only escapes characters inside text nodes, moving them into a custom node bypasses the escaping logic entirely.

2. Custom link/image handlers — overrides the default link and image handlers to correctly detect autolinks even after tree transformation, and to use angle bracket syntax (<url>) for URLs containing parentheses to avoid escaping.

3. Custom wikiLink handler — overrides the remark-wiki-link handler to output values directly without escaping.

Install

This package is ESM only. Node.js 16+ is required.

npm install remark-disable-text-escape

Usage

import { remark } from "remark";
import remarkDisableTextEscape from "remark-disable-text-escape";

const result = await remark()
  .use(remarkDisableTextEscape)
  .process("some text with [brackets] and foo_bar_baz");

console.log(String(result));
// => "some text with [brackets] and foo_bar_baz\n"

Autolinks with special characters are preserved:

const result2 = await remark()
  .use(remarkDisableTextEscape)
  .process("<http://a_b.com>");

console.log(String(result2));
// => "<http://a_b.com>\n"

Parentheses in link URLs are not escaped:

const result3 = await remark()
  .use(remarkDisableTextEscape)
  .process("[text](url(x))");

console.log(String(result3));
// => "[text](<url(x)>)\n"

With remark-wiki-link

import remarkWikiLink from "remark-wiki-link";

const result4 = await remark()
  .use(remarkWikiLink, { aliasDivider: "|" })
  .use(remarkDisableTextEscape, { aliasDivider: "|" })
  .process("[[page_name]]");

console.log(String(result4));
// => "[[page_name]]\n"

API

remarkDisableTextEscape(options?)

Plugin to disable escaping of special characters.

All special characters ([, ], (, ), *, _, &, |, ~, !, @) in text nodes will be preserved as-is in the output. Autolink format is preserved, and parentheses/ampersands/at-signs in link/image URLs are not escaped.

options.aliasDivider

Type: string Default: "|"

The alias divider used by remark-wiki-link. Set this to the same value as the aliasDivider option in your remark-wiki-link configuration.

Types

This package is written in TypeScript and ships with type definitions. It exports the LiteralChar and RemarkDisableTextEscapeOptions types.

import type {
  LiteralChar,
  RemarkDisableTextEscapeOptions,
} from "remark-disable-text-escape";

Compatibility

• Node.js 16+
• remark-stringify ^11.0.0 (peer dependency)
• remark-wiki-link ^2.0.0 (optional — wikiLink handler is only active when this plugin is used)
• ESM only — cannot be require()'d

Caveats

This plugin disables escaping of special characters ([, ], (, ), *, _, &, |, ~, !, @) in all text nodes, and prevents escaping of parentheses, ampersands, and at-signs in link/image URLs. If the output Markdown is later re-parsed, unescaped characters may be interpreted as Markdown syntax, changing the document semantics. Use this plugin only when you control the final output and do not expect round-trip fidelity.

License

MIT