@mdast2docx/core

@m2d/core

The core engine that powers mdast2docx — convert Markdown Abstract Syntax Trees (MDAST) into DOCX effortlessly.

✨ Features

• ✅ Lightweight and fast MDAST to DOCX conversion
• ✅ Works on both client-side and server-side environments
• ✅ Built-in support for section-based rendering
• ✅ Plugin-friendly architecture

Note: With a lean core, functionality can be extended via plugins such as @m2d/html, @m2d/image, @m2d/table, etc.

📦 Installation

pnpm install @m2d/core

or

yarn add @m2d/core

or

npm add @m2d/core

🚀 Usage

import { toDocx } from "@m2d/core";

const docxBlob = await toDocx(mdast, docxProps, sectionProps);

🔌 Plugins

@m2d/core supports both official and community plugins to extend its capabilities. For example:

import { toDocx } from "@m2d/core";
import { imagePlugin } from "@m2d/image";

await toDocx(mdast, docxProps, {
  plugins: [imagePlugin()],
});

🔍 Use only the plugins you need for better performance and bundle size. 🧠 You can use official plugins, or build your own custom ones to keep the bundle size minimal and functionality scoped.

@m2d/core official plugins:

Plugin	Package	Purpose
HTML	@m2d/html	Handle raw HTML nodes
Image	@m2d/image	Embed images in DOCX
Math	@m2d/math	Render LaTeX math
Table	@m2d/table	Markdown tables
List	@m2d/list	Advanced list formatting
Extended MDAST	@m2d/mdast	Extended mdast types

📜 API

toDocx(astInputs, docxProps, defaultSectionProps, outputType?)

Param	Type	Description
astInputs	Root or { ast: Root; props?: ISectionProps }[]	The parsed Markdown AST
docxProps (optional)	IDocxProps	Document metadata and style
defaultSectionProps (optional)	ISectionProps	Default layout configuration for sections
outputType (optional)	OutputType	(defaults to 'blob')

Returns a Promise resolving to a DOCX Blob, Buffer, or Base64 string.

ISectionProps

The ISectionProps interface extends DOCX section options with additional MDAST conversion properties:

interface ISectionProps {
  // DOCX section properties (headers, footers, page settings, etc.)
  // ... all ISectionOptions properties except 'children'
  
  // MDAST to DOCX conversion properties
  useTitle?: boolean;           // H1 as title, H2 as Heading1, etc. (default: true)
  plugins?: Array<IPlugin>;     // Plugins to extend conversion functionality
  trimInnerSpaces?: boolean;    // Trim multiple whitespaces in text (default: true)
  footnoteProps?: MutableParaOptions & MutableRunOptions; // Custom footnote styling
}

Key Properties:

• useTitle - Controls heading hierarchy mapping (default: true)
• plugins - Array of plugins to extend conversion capabilities
• trimInnerSpaces - Normalizes whitespace in text nodes (default: true)
• footnoteProps - Custom paragraph and run styling for footnote content
• Plus all standard DOCX section properties for page layout, headers, footers, etc.

🤖 Generative AI Use-case

AI tools often generate Markdown — @m2d/core helps convert them into rich DOCX reports or presentations. This is useful in:

• AI-generated blogs, documentation, and research reports
• Client-side and server-side rendering of AI-generated content
• Integrating in GenAI pipelines with format export capabilities

💡 Inspiration & Relevance

This library is especially useful in:

• Generative AI — Convert Markdown outputs (e.g., from ChatGPT, LLMs) to downloadable DOCX reports
• Developer Tools — Export Markdown-based documentation or changelogs as DOCX
• Education — Convert notes, quizzes, or assignments authored in Markdown

✅ Works both on client side and server side — offload to browser or use high-performance Node.js.

🛠️ Development

git clone https://github.com/tiny-md/mdast2docx
cd mdast2docx/m2d/core
pnpm install
pnpm dev

📄 License

Licensed under the MPL-2.0 License.

⭐ Support Us

If you find this useful:

• ⭐ Star mdast2docx on GitHub
• ❤️ Consider sponsoring

Made with 💖 by Mayank Kumar Chaudhari

with @m2d/core, bring structure, style, and extensibility to your Markdown-to-DOCX pipeline.