Grid Table Plugin

The @ampernic/markdown-it-grid-table plugin adds extended ASCII table syntax to Markdown documents in VitePress.

Installation

npm install @ampernic/markdown-it-grid-table

Usage in VitePress

Register the plugin in the VitePress config:

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress';
import gridTablePlugin from '@ampernic/markdown-it-grid-table';

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(gridTablePlugin);
    }
  }
});

Table syntax

The plugin accepts tables drawn as ASCII borders made of +, - and = characters.

Basic table

+-------+-------+
| Column 1 | Column 2 |
+=======+=======+
| Data 1 | Data 2 |
+-------+-------+

Multi-line cells

+-------------+-------------+
| Header A    | Header B    |
+=============+=============+
| Cell        | Text        |
| with        | in the      |
| line        | second      |
| breaks      | column      |
+-------------+-------------+

Markdown inside a table

Here is what the rendered table looks like:

Product	Price
Graphics card	$799
CPU	$349
RAM	$129

Column alignment

Colons in the top or bottom border set alignment (Pandoc style):

+--------+:-------:+-------:+
| Left   | Center  | Right  |
+========+=========+========+
| a      | b       | c      |
+--------+---------+--------+

A headerless table encodes colons directly in the top border (+:---:+---:+), with no +===+ separator row.

Caption and anchor

A trailing : Caption {#id} line turns into <caption> inside the <table> and puts id on the <table> itself, so it can be linked to:

+---+---+
| a | b |
+===+===+
| 1 | 2 |
+---+---+

: Parameters table {#params}

Options

Options are passed as the second argument to md.use(gridTablePlugin, options):

Option	Type	Default	Description
enableAlign	boolean	true	Parse : in borders as column alignment
enableMultiLine	boolean	true	Allow multi-line cells
vitepress	boolean	true	Sets class="{prefix}-table" and overrides VitePress's table_open renderer (otherwise VitePress overwrites attributes with its own <table tabindex="0">)
classPrefix	string	"vp"	<table> class prefix (vp-table, custom-table, ...)