@mdast2docx/list

@m2d/list

@m2d/list: Markdown List & Numbering conversion plugin for @m2d/core. Transforms ordered and bullet lists into native Word OpenXML numbering schemes.

---

Features

• Hierarchical Decimal Numbering: Generates clear, multi-level outline numbering (1., 1.1., 1.1.1., A., a., i.) that avoids resetting arbitrarily at sub-levels.
• Multi-Tier Bullet Glyphs: Automatically assigns distinct bullet characters (●, ○, ■, ◆, ▶, etc.) across nested list levels.
• Native Word OpenXML Numbering: Registers genuine Word abstract numbering schemes in numbering.xml, ensuring list items update dynamically in Word.
• Fully Customizable Levels: Use the exported createLevels utility to define custom indentation steps, start depths, and format sequences.
• Word Preset Support: Toggle defaultBullets: true to seamlessly match standard Word template bullet configurations.

---

Installation

This package (@mdast2docx/list) is an official alias of @m2d/list.

Why does this exist?

We provide this package to offer shorter import paths and improved discoverability. While both packages provide identical functionality, @m2d/list is the primary source of truth.

Which one should I use?

• Use @mdast2docx/list if you prefer the shorter name or specific branding or ESM Only.
• Use @m2d/list for the most stable long-term reference and standard alignment.

Feature	@m2d/list	@mdast2docx/list
Source Code	Primary	Proxy
Updates	Immediate	Synchronized (Immediately)
Bundle Size	100%	100% (Zero overhead)
Format	ESM + CJS	ESM Only
Maintenance	Primary	Proxy (inherits)
Security	Primary	Proxy (inherits)

Maintenance & Support

Security: Security audits are performed on the canonical package; this alias inherits all security patches automatically.

---

$ pnpm add @m2d/list @m2d/core docx

or

$ npm install @m2d/list @m2d/core docx

or

$ yarn add @m2d/list @m2d/core docx

---

Quick Start

import { toDocx } from "@m2d/core";
import { listPlugin } from "@m2d/list";
import remarkParse from "remark-parse";
import { unified } from "unified";

const markdown = `
# Project Plan

1. Inception Phase
   1. Requirements Gathering
   2. Stakeholder Review
2. Implementation Phase
   1. Core Engine Development
      - Microservices architecture
      - Message queues
   2. Quality Assurance
`;

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

const docxBlob = await toDocx(mdast, {}, {
  plugins: [listPlugin()],
});

---

Plugin Options

import { ILevelsOptions } from "docx";

export interface IListPluginOptions {
  /** Defines custom numbering styles for ordered lists */
  levels?: ILevelsOptions[];

  /** Defines custom numbering styles for bullet lists */
  bulletLevels?: ILevelsOptions[];

  /** Bullet characters used for unordered lists (default: ["●", "○", "■", "◆", ...]) */
  bullets?: string[];

  /** If true, uses Word's default bullet styles instead of custom ones (default: false) */
  defaultBullets?: boolean;
}

---

Deep Dive Guides

• Ordered Lists & Hierarchical Numbering Guide: Multi-level decimal numbering schemas, outline sequences, and the createLevels helper.
• Bullet Styles & Nesting Guide: Bullet glyph hierarchies, custom characters, and Word native preset modes.

---

License

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

---

with by Mayank Kumar Chaudhari