@mdit/plugin-stylize
Plugin for stylizing tokens.
Usage
import { stylize } from "@mdit/plugin-stylize";
import MarkdownIt from "markdown-it";
const mdIt = new MarkdownIt().use(stylize, {
config: [
// your options
],
});
mdIt.render("Check FAQ for more details._Recommended_");The config option receives an array, where each element accepts 2 options:
matcher: should bestringorRegExp.replacer: a function customizing the matched token. It receives the tokentag,content,attrsand the Markdownenvobject.
Configs from localConfigGetter are tried first, then the global config ones; within each list, configs are tried in order. A config is only applied when its replacer returns a result: if the matcher matches but the replacer returns null or undefined, the next matching config is tried. This makes it possible to configure several rules for the same token.
For example, you can use the following config to transform *Recommended* into a Badge <Badge type="tip">Recommended</Badge>:
mdIt.use(stylize, {
config: [
{
matcher: "Recommended",
replacer: ({ tag }) => {
if (tag === "em")
return {
tag: "Badge",
attrs: { type: "tip" },
content: "Recommended",
};
},
},
],
});Another example is you want a to set all the emphasis n’t words to red color, so that Setting this to a invalid syntax *doesn’t* have any effect. becomes: "Setting this to a invalid syntax doesn’t have any effect."
mdIt.use(stylize, {
config: [
{
matcher: /n’t$/,
replacer: ({ tag, attrs, content }) => {
if (tag === "em")
return {
tag: "span",
attrs: { ...attrs, style: "color: red" },
content,
};
},
},
],
});Also, we provide a localConfigGetter to receive env object in case you want to apply local rules in certain situations.
mdIt.use(stylize, {
localConfigGetter: (env) => env?.stylize ?? [],
});
mdIt.render("Check FAQ for more details._Recommended_", {
stylize: [
{
matcher: "Recommended",
replacer: ({ tag }) => {
if (tag === "em")
return {
tag: "Badge",
attrs: { type: "tip" },
content: "Recommended",
};
},
},
],
});Performance
To avoid performance impact, you should try to avoid using RegExp for better performance unless you need it.
Also try to create snippets with RegExp having lower costs, e.g: RegExp starting with ^ and ending with $.
For example, if you only want to match "SHOULD", "MUST" and "MAY", you should write /^(?:SHOULD|M(?:UST|AY))$/u instead of /SHOULD|MUST|MAY/u. The fist one will only match 2 time with "A loo...oong content" with 1000 characters, but will match nearly 3000 times with the second RegExp.
Options
MarkdownItStylizeConfig<MarkdownEnv>[]interface MarkdownItStylizeResult {
/** Tag name */
tag: string;
/** Attributes settings */
attrs: Record<string, string | number>;
/** Tag content */
content: string;
}
interface MarkdownItStylizeConfig<MarkdownEnv extends Record<string, any> = Record<string, any>> {
/** Inline token matcher */
matcher: string | RegExp;
/** Content Replacer */
replacer: (options: {
tag: string;
content: string;
attrs: Record<string, string | number>;
env: MarkdownEnv;
}) => MarkdownItStylizeResult | null | undefined;
}Stylize config array. Each config contains a matcher (string or RegExp) and a replacer function. Local configs are tried first, then the global ones; within each list, configs are tried in order until a replacer returns a result.
MarkdownEnv is an optional type parameter of the plugin options (defaulting to Record<string, any>); the env argument is always provided to replacer.
(env?: MarkdownEnv) => MarkdownItStylizeConfig<MarkdownEnv>[] | nullLocal config getter. Takes environment object and returns local stylize config.