@m2d/table

A plugin that converts Markdown tables into rich, styled Word tables with full alignment, border, and header support.

---

📦 Installation

npm install @m2d/table

pnpm add @m2d/table

yarn add @m2d/table

---

🚀 Overview

The @m2d/table plugin for mdast2docx renders Markdown tables into Word-compatible tables with customizable layout, alignment, and cell styling using the docx library.

Automatically handles header rows, borders, shading, cell alignments, and padding — all configurable.

---

✨ Features

• Transforms Markdown tables into docx.Table elements
• Auto-detects column alignment from MDAST (left, center, right)
• Customizable:
  • Table width and border styles
  • Cell padding and shading
  • Header row formatting
  • Horizontal and vertical alignment
• Graceful fallback to defaults if MDAST alignment is missing

---

🛠️ Usage

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

const plugins = [tablePlugin()];

const buffer = await toDocx(mdastTree, {
  plugins,
});

---

⚙️ Options

The tablePlugin accepts an optional configuration object:

tablePlugin({
  tableProps: { ... },
  rowProps: { ... },
  cellProps: { ... },
  firstRowProps: { ... },
  firstRowCellProps: { ... },
  alignments: {
    defaultHorizontalAlign: AlignmentType.CENTER,
    defaultVerticalAlign: VerticalAlign.CENTER,
    preferMdData: true,
  },
});

All options override the following sensible defaults:

Default Table Style

Property	Default Value
Table Width	100% (percentage)
Border Style	SINGLE, size 1
Cell Padding	2–4mm margins (top/bottom/left/right)
Header Row	Bold with shaded background #b79c2f
Vertical Alignment	CENTER
Horizontal Alignment	Based on Markdown or CENTER fallback

---

🧪 Example

Markdown Input

| Name  | Age |      City |
| :---: | :-: | --------: |
| Alice | 24  |  New York |
|  Bob  | 30  | San Diego |

Output DOCX

• The first row is treated as a header, with custom shading.
• Column alignment is preserved: center, center, right.

---

🔍 Internals

• Leverages docx.Table, docx.TableRow, docx.TableCell, and docx.Paragraph
• Dynamically maps Markdown alignment via MDAST.align[]
• Uses @m2d/core’s block plugin API
• Prevents re-processing of transformed nodes by setting node.type = ""

---

⚠️ Limitations

• Does not support row/column spans
• MDAST source must conform to GFM tables
• Table styling is fixed to plugin options; no per-cell customization via Markdown yet

---

⭐ Support Us

If you find this useful:

• ⭐ Star mdast2docx on GitHub
• ❤️ Consider sponsoring

---

🧾 License

MIT © Mayank Chaudhari

---

Made with 💖 by Mayank Kumar Chaudhari