https://github.com/md2docx/table
Plugin to convert Markdown tables (MDAST) to DOCX with support for rich formatting and seamless integration into mdast2docx.
https://github.com/md2docx/table
Last synced: 3 months ago
JSON representation
Plugin to convert Markdown tables (MDAST) to DOCX with support for rich formatting and seamless integration into mdast2docx.
- Host: GitHub
- URL: https://github.com/md2docx/table
- Owner: md2docx
- License: mpl-2.0
- Created: 2025-03-25T19:05:02.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-26T09:02:35.000Z (3 months ago)
- Last Synced: 2026-03-26T12:41:21.804Z (3 months ago)
- Language: TypeScript
- Size: 1.97 MB
- Stars: 1
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: contributing.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# `@m2d/table` 
[](https://github.com/md2docx/table/actions/workflows/test.yml) [](https://codecov.io/gh/md2docx/table) [](https://www.npmjs.com/package/@m2d/table)  
> A plugin that converts Markdown tables into rich, styled Word tables with full alignment, border, and header support.
---
## 📦 Installation
```bash
npm install @m2d/table
```
```bash
pnpm add @m2d/table
```
```bash
yarn add @m2d/table
```
---
## 🚀 Overview
The `@m2d/table` plugin for [`mdast2docx`](https://github.com/mayankchaudhari/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
```ts
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:
```ts
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
```ts
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
```md
| 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](https://github.github.com/gfm/#tables-extension-)
- Table styling is fixed to plugin options; no per-cell customization via Markdown yet
---
## ⭐ Support Us
If you find this useful:
- ⭐ Star [mdast2docx](https://github.com/tiny-md/mdast2docx) on GitHub
- ❤️ Consider [sponsoring](https://github.com/sponsors/mayank1513)
---
## 🧾 License
MIT © [Mayank Chaudhari](https://github.com/mayankchaudhari)
---
Made with 💖 by Mayank Kumar Chaudhari