@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