markdown-it-mojicolor

English | 日本語

The markdown-it plugin that allows you to change the text color of Markdown.

TOC

• Setup
• Quick usage
• Usage
• Options
• Automatic bold and italic colors
• Markdown inside colored text
• Additional color dictionaries
• Changelog
• Development
• Reference Website
• Extensions

Setup

Install via npm:

npm install markdown-it markdown-it-mojicolor

Use with markdown-it:

const 
    md = require('markdown-it')(),
    plugin = require("markdown-it-mojicolor");

md.use(plugin);

Quick usage

| Input | Render | Description | | ---------------------------- | ------------------------------------------------------ | ------------------------------------------------ | | %Tomato%{tomato} | <span style="color: tomato;">Tomato</span> | Specified by color. | | %Orange%{#ffa500} | <span style="color: #ffa500;">Orange</span> | Specified in hexadecimal. | | %café au lait%{カフェオレ} | <span style="color: #946c45;">café au lait</span> | Specified in Japanese, converted to hexadecimal. | | %Aqua%{rgb(0,255,255)} | <span style="color: rgb(0,255,255);">Aqua</span> | Specified in RGB. | | %Bisque%{hsl(33,100%,88%)} | <span style="color: hsl(33,100%,88%);">Bisque</span> | Specified in HSL. |

Usage

A markdown-it plugin that converts %character%{color} to <span style="color: color">character</span>.

Colors should be specified as color word, hexadecimal, RGB or HSL.

It also supports Japanese. For example, if you specify カフェオレ meaning café au lait, it will be converted to #946c45, which closely resembles the color of café au lait.

To find out which colors are supported, refer to Traditional Colors of Japan - Dictionary of Japanese Colors.

Options

Register the plugin once per markdown-it instance. Both options are optional:

| Option | Default | Accepted values | | --- | --- | --- | | colorFiles | [] | Array of absolute JSON file paths, applied in order | | styles | {} | Object with bold and/or italic, each a color string or null |

Omitting both keeps explicit %...%{color} coloring without automatic colors. styles: null and colorFiles: null are invalid; null is supported only as the value of bold or italic in styles or a per-document settings object (for example, styles: { bold: null }). %text%{null} does not disable automatic coloring. Omit a style property to inherit it: an explicitly supplied bold: undefined is invalid.

Automatic bold and italic colors

const md = require('markdown-it')();
const plugin = require('markdown-it-mojicolor');
md.use(plugin, { styles: { bold: 'blue', italic: 'green' } });

const parsedFrontMatter = {
    markdown: {
        mojicolor: { bold: 'yellow', italic: null }
    }
};
md.render('**Bold** and *italic*', { frontmatter: parsedFrontMatter });

styles supports bold and italic. Values use the same built-in and additional color dictionaries as inline colors. Per-document env.frontmatter.markdown.mojicolor overrides each supplied setting; omitted settings inherit the plugin defaults. Set an individual value to null to remove automatic coloring for that element. In the example, bold is yellow and italic has no automatic color declaration.

An absent front matter path, frontmatter: null, markdown: null, mojicolor: null, and an empty mojicolor object are safe and add no document overrides. An individual bold: null or italic: null is different: it explicitly removes that automatic color. Empty strings, invalid types and unsupported setting names throw errors. Options are validated during registration and document settings during rendering. The plugin does not modify the options, env, front matter or settings objects, and document settings apply only to that render.

Priority is options.styles (including values supplied from VS Code settings) < env.frontmatter.markdown.mojicolor < %...%{color}. Inside an explicit color scope, automatic coloring is not applied: %**Blue**%{blue} remains blue and bold even with bold: 'yellow' in front matter. Outside explicit scopes, an inner Markdown element's configured color takes precedence over its parent's inherited color.

This plugin does not extract or parse YAML. The caller removes the front matter from the Markdown body, parses the complete YAML object, and passes it through env.frontmatter:

For example, a caller can translate this front matter:

---
markdown:
  mojicolor:
    bold: yellow
    italic: null
---

const env = { frontmatter: parsedFrontMatter };
const html = md.render(body, env);

With the defaults above, normal bold text becomes yellow and italic text receives no automatic color declaration. %**Blue**%{blue} still produces <span style="color: blue;"><strong>Blue</strong></span>. Setting an individual value to null removes this plugin's automatic declaration; the element can still inherit a parent's color or receive host CSS styles.

The legacy env.markdownMojicolor input remains supported as a fallback for compatibility, but is deprecated for new integrations. It is read only when env.frontmatter.markdown.mojicolor is absent. When the new mojicolor property is present, its object is authoritative and is not merged with the legacy object; an empty object or null therefore uses only the plugin defaults.

Settings apply to one render call and do not carry over to later documents. YAML parsing, VS Code settings, workspace-relative path resolution and preview refresh belong to the caller; the examples here do not imply those integrations are implemented in the VS Code extension.

Markdown inside colored text

The body of %...%{color} supports Markdown inline formatting:

%**Bold** and *italic*%{blue}
%[Link](https://example.com)%{blue}
%`inline code`%{blue}

For example, %**Blue**%{blue} produces <span style="color: blue;"><strong>Blue</strong></span>. Markdown options such as HTML handling and line breaks still apply. Links and code may have their own colors in the host's stylesheet.

A lone percent sign is ordinary body text (%100% complete%{blue}). An unescaped %{ outside a code span closes the body; use \%{ for literal text. Code spans with matching backtick delimiters can contain %{ without closing the color scope.

Nesting color expressions is not supported. The first closing marker wins: %outer %inner%{red}%{blue} colors outer %inner red and leaves %{blue} after it. Markdown emphasis cannot start inside a color scope and end outside it (or vice versa).

Additional color dictionaries

Pass absolute JSON file paths through colorFiles:

const path = require('path');
const md = require('markdown-it')();
const plugin = require('markdown-it-mojicolor');
md.use(plugin, {
    colorFiles: [path.resolve('colors/common.json'), path.resolve('colors/project.json')]
});

Each file contains a dictionary such as { "brand": "#00a6da" }. Use it with %Text%{brand}. Additional files override built-in colors; later files override earlier files. Names are case-sensitive. Values are CSS color strings, and are not recursively resolved as other dictionary names. The // key is reserved for source metadata and ignored.

Create colors/common.json and colors/project.json before running the example. For example, put { "brand": "#111111", "warning": "orange" } in the first and { "brand": "#00a6da" } in the second. brand then resolves to #00a6da, while warning remains orange. The same names can be used in styles, env.frontmatter.markdown.mojicolor and the legacy env.markdownMojicolor input.

path.resolve() in this example uses the calling process's working directory. To resolve relative to a CommonJS script instead, use path.join(__dirname, 'colors/common.json'). The plugin itself requires absolute paths and does not watch files.

The four built-in dictionaries are data/jp_colors.json, data/intl_colors.json, data/metro_colors.json and data/rail_colors.json. Their existing first-match order is retained; additional files override the resulting dictionary. JSON must be an object with nonempty names and string values, rather than an array. JSON comments are not supported: "//" is an ordinary metadata property, not comment syntax.

Files are read once when the plugin is registered. Create a new markdown-it instance and register the plugin again to load changed files. Relative paths, missing files, invalid JSON, and invalid definitions throw during registration. File errors include the path. Color values must be nonempty strings; declaration separators, braces, backslashes, control characters and CSS comment delimiters are rejected. This is not full CSS syntax validation. Unknown color names are passed through to CSS; rejected inline values are left to normal Markdown parsing.

Development

See test/README.md for the Node.js 24 development environment, test commands, Lint and verification scope. Tests currently use markdown-it 14.x with CommonJS; they do not establish compatibility with other major versions.

Reference Website

• Traditional Colors of Japan - Traditional Colors of Japan
• Traditional Colors of World
• Symbol Colors of Subway Metro Colors - Metro Colors
• Rail Colors

The original site (https://www.colordic.org/) has granted us permission to publish and use the site on OSS.

Extensions

• yusu79/vscode-markdown-mojicolor