@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: {
    ... // CellProps
    data: { bold: true, color: "#000000" } // Paragraph and Run styling options
  },
  firstRowProps: { ... },
  firstRowCellProps: {
    data: { bold: true, alignment: AlignmentType.CENTER } // Header cell styling
  },
  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
Cell Styling	Full docx.js paragraph & run options
Vertical Alignment	CENTER
Horizontal Alignment	Based on Markdown or CENTER fallback

Advanced Cell Styling with data Property

The data property provides comprehensive styling control using docx.js paragraph and text run options:

Text Run Styling (IRunOptions)

• bold, italics, underline, strike, doubleStrike
• color, size (font size in half-points)
• font (font family), highlight, shading
• superScript, subScript, smallCaps, allCaps

Paragraph Styling (IParagraphOptions)

• alignment - text alignment (LEFT, CENTER, RIGHT, JUSTIFIED)
• spacing - line spacing and paragraph spacing
• indent - left, right, first line, hanging indents
• numbering, bullet, style

Code Block Support

• pre: true - preserves spaces, newline for code blocks

tablePlugin({
  cellProps: {
    data: {
      font: "Arial",
      size: 20, // 10pt font
      color: "#333333",
      spacing: { after: 120 }, // 6pt spacing after
    },
  },
  firstRowCellProps: {
    data: {
      bold: true,
      alignment: AlignmentType.CENTER,
      color: "#ffffff",
      size: 24, // 12pt font
      font: "Calibri",
    },
  },
});

---

🧪 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