Skip to Content
Md2Docx logo Md2Docx

Overview

Updated 10 Nov 2026

CIcodecovnpm versionnpm downloadsnpm bundle sizelicense

@m2d/code-shiki: VS Code-grade syntax highlighting plugin for md2docx powered by shiki. Delivers precision TextMate grammar tokenization, lifecycle pre-warming via AST scanning, preset Word themes, gutter line numbers, and Run Coalescing into clean OpenXML.

✨ Features

  • ⚡ Powered by Shiki & TextMate: Real TextMate grammar tokenization matching the exact highlighting fidelity of VS Code.
  • 🔄 AST Lifecycle Pre-warming: Automatically inspects MDAST document trees during preprocess to load language grammars on demand.
  • 🎨 Authentic Word Themes: Includes github-light, github-dark, monokai, and executive-print with native OpenXML background shading (<w:shd w:fill="HEX">).
  • 🔢 Gutter Line Numbering: Render code blocks as 2-column Word tables with right-aligned, muted line number columns.
  • ⚡ OpenXML Run Coalescing: Automatically combines adjacent tokens with matching styles to cut <w:r> XML node bloat by 30%–50%.
  • 🛡️ Git Diff Highlighting: Supports diff additions (+) and deletions (-) with green and red run/background tints.
  • 🔌 Flexible Initialization: Supports direct synchronous instantiation with a pre-configured highlighter, async pre-warming via createCodeShiki, or zero-config automatic AST warmup.

📦 Installation

$ pnpm add @m2d/code-shiki @m2d/core docx shiki

or

$ npm install @m2d/code-shiki @m2d/core docx shiki

or

$ yarn add @m2d/code-shiki @m2d/core docx shiki

🚀 Quick Start

Zero-Config Auto Warmup

import { toDocx } from "@m2d/core";
import { codeShikiPlugin } from "@m2d/code-shiki";
import remarkParse from "remark-parse";
import { unified } from "unified";

const markdown = `
# Architecture Spec

\`\`\`typescript showLineNumbers
import { createServer } from "node:http";

const server = createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ status: "healthy" }));
});

server.listen(8080);
\`\`\`
`;

const ast = unified().use(remarkParse).parse(markdown);

const docxBlob = await toDocx(
  ast,
  {},
  {
    plugins: [
      codeShikiPlugin({
        theme: "github-dark",
        lineNumbers: true,
      }),
    ],
  },
  "blob",
);

Pre-Warmed Factory

import { toDocx } from "@m2d/core";
import { createCodeShiki } from "@m2d/code-shiki";

const shikiPlugin = await createCodeShiki({
  theme: "executive-print",
  lineNumbers: true,
  langs: ["typescript", "python", "rust"],
});

const docxBlob = await toDocx(ast, {}, { plugins: [shikiPlugin] }, "blob");

⚙️ Plugin Options

OptionTypeDefaultDescription
themePresetThemeName | (string & {}) | ICodeTheme"github-light"Active theme ("github-light", "github-dark", "monokai", "executive-print", or custom theme).
highlighterShikiHighlighterundefinedOptional pre-configured Shiki highlighter instance.
shikiThemestring"github-light"Shiki theme identifier to use during tokenization.
lineNumbersbooleanfalseWhen true, renders multi-line code blocks as 2-column tables with line numbers.
fontFamilystring"Consolas"Monospace font family for Word code runs.
fontSizenumber19Half-points font size (19 = 9.5pt).
diffHighlightbooleantrueHighlights unified diff additions (+) and deletions (-).

License

This library is licensed under the MIT open-source license.

with 💖 by Mayank Kumar Chaudhari

On this page

✨ Features📦 Installation🚀 Quick StartZero-Config Auto WarmupPre-Warmed Factory⚙️ Plugin OptionsLicense