A highly extensible, zero-code block container and inline directive syntax engine for markdown-it.
markdown-it-extensible allows developers and end-users to create, modify, or extend custom Markdown syntax elements—such as custom styled callout boxes (::: warning-box [Title]) or inline highlights (:mark[Text])—purely via JavaScript options, JSON configuration, or CSS classes, without writing custom Regex parsers or modifying plugin source code.
- 📦 Dynamic Block Containers (
::: name [Title]): Add or customize custom callouts with optional title headers. - 🎨 Dynamic Inline Directives (
:name[Content]): Map custom inline markup to any CSS class or HTML tag (<strong>,<mark>,<span>, etc.). - 🚀 Zero-Code CSS Fallback: Use any
:class-name[Text]in Markdown—it automatically renders<span class="class-name">Text</span>without needing JavaScript registration. - 📐 Multi-Level Nesting & Case-Insensitive Matching: Handles
::::nesting and case-insensitive container names (::: Grammar-Box,::: GRAMMAR-BOX). - 📚 Built-in Scholarly Syntax: Native support for Sanskrit Devanagari brackets (
《धर्मः》), intra-table line breaks (:br), and intra-table indents (:indent). - 🔷 TypeScript First Class Support: Comes with
index.d.tsproviding full autocomplete, hover docs, and type safety in VS Code and WebStorm. - 🛠 Programmatic Syntax Help API: Exposes
getSyntaxHelp()so host applications (like Zentauri, Payer, or custom editors) can dynamically render help modals and cheatsheets.
npm install markdown-it-extensibleconst MarkdownIt = require('markdown-it');
const extensiblePlugin = require('markdown-it-extensible');
const md = new MarkdownIt({ html: true }).use(extensiblePlugin);
// Render Markdown with default containers and directives
const html = md.render(`
::: grammar-box [Grammatischer Hinweis]
Klassifikation der Vokale und Konsonanten.
:::
Dies ist :sig[Signalrot-Text] und :mark[gelb markierter Text].
`);
console.log(html);Pass a custom array to blockContainers when initializing the plugin. Each container maps a Markdown trigger name to a generated HTML CSS class <div class="{className} custom-block">.
md.use(extensiblePlugin, {
blockContainers: [
{ name: 'warning-box', className: 'alert-red' },
{ name: 'solution', className: 'solution-card' },
{ name: 'info', className: 'info-box' }
]
});::: warning-box [Achtung!]
Dies ist eine rot hervorgehobene Warnungsbox.
:::<div class="alert-red custom-block">
<div class="md-box__title">Achtung!</div>
<p>Dies ist eine rot hervorgehobene Warnungsbox.</p>
</div>Pass a custom array to inlineDirectives. You can define the trigger name, the generated CSS class, and the target HTML tag (e.g. strong, mark, span, em, ins).
md.use(extensiblePlugin, {
inlineDirectives: [
{ name: 'highlight', className: 'marker-green', tag: 'mark' },
{ name: 'danger', className: 'text-red-600', tag: 'strong' },
{ name: 'badge', className: 'pill-badge', tag: 'span' }
]
});Das ist :highlight[grün markierter Text] und ein :badge[v1.0.0] Badge.Das ist <mark class="marker-green">grün markierter Text</mark> und ein <span class="pill-badge">v1.0.0</span> Badge.If a user writes :any-custom-class[Some Text] in Markdown without registering it beforehand in JavaScript, markdown-it-extensible automatically falls back to rendering:
<span class="any-custom-class">Some Text</span>This allows non-technical users or template designers to introduce new inline styles purely by writing a new class in their CSS stylesheet!
When you pass your own blockContainers or inlineDirectives array, only the elements explicitly listed in your array are registered. This allows host applications to disable default containers or restrict users to specific allowed syntax blocks.
// Only allow 'note-box' and disable all other default containers
md.use(extensiblePlugin, {
blockContainers: [
{ name: 'note-box', className: 'note-box' }
]
});Applications (like desktop editors, web previewers, or documentation generators) can query syntax help programmatically directly from the plugin:
const extensiblePlugin = require('markdown-it-extensible');
// Retrieve syntax metadata for Help Modals or Cheatsheets
const help = extensiblePlugin.getSyntaxHelp();
console.log(help.containers);
// [ { syntax: '::: grammar-box [Titel]', description: 'Erstellt den Block-Container .grammar-box' }, ... ]
console.log(help.inline);
// [ { syntax: ':sig[Text]', description: 'Erzeugt <strong class="signalrot">Text</strong>' }, ... ]
// Access default arrays directly
console.log(extensiblePlugin.DEFAULT_BLOCK_CONTAINERS);
console.log(extensiblePlugin.DEFAULT_INLINE_DIRECTIVES);markdown-it-extensible includes full TypeScript definitions in index.d.ts. When configuring the plugin, your IDE will provide autocomplete for options and parameter descriptions:
import MarkdownIt from 'markdown-it';
import extensiblePlugin, { ScholarlyPluginOptions } from 'markdown-it-extensible';
const options: ScholarlyPluginOptions = {
injectStyles: true,
blockContainers: [
{ name: 'custom-card', className: 'custom-card' }
]
};
const md = new MarkdownIt().use(extensiblePlugin, options);By default (injectStyles: true), the plugin automatically injects its theme CSS into rendered output.
If you prefer importing CSS in your frontend bundle (Vite, Next.js, Webpack):
// Disable automatic inline injection
md.use(extensiblePlugin, { injectStyles: false });// Import CSS in your frontend entry file
import 'markdown-it-extensible/css';| Syntax | Rendered Class |
|---|---|
::: grammar-box [Titel] |
<div class="grammar-box custom-block"> |
::: grammar-box2 [Titel] |
<div class="grammar-box2 custom-block"> |
::: important [Titel] |
<div class="important custom-block"> |
::: note-box [Titel] |
<div class="note-box custom-block"> |
::: media |
<div class="media custom-block"> |
::: center |
<div class="center custom-block"> |
::: indent |
<div class="indent custom-block"> |
::: compact |
<div class="compact custom-block"> |
::: metrik-schema |
<div class="metrik-schema custom-block"> |
::: deleteme-box |
<div class="deleteme-box custom-block"> |
| Syntax | Rendered HTML |
|---|---|
:sig[Text] |
<strong class="signalrot">Text</strong> |
:mark[Text] |
<mark class="marker-yellow">Text</mark> |
《संस्कृतम्》 |
<span class="sanskrit-dev" translate="no" lang="sa">संस्कृतम्</span> |
《धर्मः ||》 |
<span class="sanskrit-dev" translate="no" lang="sa">धर्मः ॥</span> |
:br |
<br> (Inside Markdown tables) |
:indent |
<span class="indent-inline"></span> (Inside Markdown tables) |
markdown-it-extensible serves as the single source of truth for:
- VS Code Extension:
extensible-markdown(Provides live autocomplete snippets in VS Code) - Zentauri Desktop Editor
- Payer Web Application
MIT © marcodem