@felisdiligens/md-table-tools v0.2.0

Warning
Work in progress. API may change in the future, bugs may rear their ugly head...
Use with care! If in doubt, ask me. :)

MultiMarkdown table tools

Screenshot of web demo

Features

• Parsing MultiMarkdown, GitHub-flavored Markdown, HTML, DokuWiki, or CSV tables into intermediary
• Converting intermediary back to MultiMarkdown, GitHub-flavored Markdown, HTML, DokuWiki, or CSV tables
• Formatting or minifying MultiMarkdown or GFM tables
• Manipulating parsed/intermediary tables (⚠️ possibly buggy, please run Table.update() after making any changes), e.g.
  • by adding, deleting, or moving rows/columns
  • by changing the content of table cells
  • by merging or splitting table cells
  • by changing the text alignment within a column
  • etc.

Module

This project gets packaged as CommonJS and ES module. Types are generated as well.

To install, run

npm i @felisdiligens/md-table-tools

Usage / Examples

Web demo

A web demo (see screenshot above) can be accessed here.

The source code is under ./demo.

CLI demo

$ npm run demo

import { MultiMarkdownTableParser } from "@felisdiligens/md-table-tools";
import { HTMLTableRenderer } from "@felisdiligens/md-table-tools";

const mdParser = new MultiMarkdownTableParser();
const htmlRenderer = new HTMLTableRenderer();

var mdTable = `
| Example | table  |
|---------|--------|
| Hello   | world! |
`;

// Parse markdown to intermediary:
var intermediaryTable = mdParser.parse(mdTable);

// Make some changes:
intermediaryTable.getCell(1, 1).setText("everyone!");
intermediaryTable.update();

// Render as HTML:
var htmlTable = htmlRenderer.render(intermediaryTable);

/* Output:
<table>
  <thead>
    <tr>
      <th>Example</th>
      <th>table</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Hello</td>
      <td>everyone!</td>       <--- Changed!
    </tr>
  </tbody>
</table>
*/

Projects

See my Joplin plugin as an example for usage.

Docs

You can access the documentation here: ./docs/modules.md.
Or click on one of the classes below:

• All classes implementing the interface TableRenderer:
  You can always use the TableRenderer.render(Table) method to get a rendered string.
  • PrettyMultiMarkdownTableRenderer
  • MinifiedMultiMarkdownTableRenderer
  • GitHubFlavoredMarkdownTableRenderer
  • HTMLTableRenderer
  • CSVTableRenderer
  • DokuWikiTableRenderer
• All classes implementing the interface TableParser:
  You can always use the TableParser.parse(string) method to get an intermediary Table object.
  • MultiMarkdownTableParser
  • GitHubFlavoredMarkdownTableParser
  • HTMLTableParser
  • CSVTableParser
  • DokuWikiTableParser
• Intermediary classes:
  You can access rows, columns, cells, and the caption from the Table parent class.
  Use these to manipulate the table. Don't forget to run Table.update() method afterwards!
  • Table
  • TableRow
  • TableColumn
  • TableCell
  • TableCaption
• Enums:
  • TextAlignment
  • TableCellMerge
  • TableCaptionPosition
  • HTMLTableParserMode
  • CSVTableRendererMode

Development

Building

$ git clone https://github.com/FelisDiligens/md-table-tools.git
$ cd md-table-tools
$ npm install
$ npm run build

Testing

$ npm run test

MultiMarkdown Syntax

This module mostly follows the MultiMarkdown specs: https://fletcher.github.io/MultiMarkdown-6/syntax/tables.html

With a few exceptions:

• You can merge cells vertically by writing ^^ into a cell.
• You can use \ to join rows together.

Differences to tables in GitHub-flavored Markdown (and similar variants)

GitHub-flavored Markdown tables (and similar variants) are fully supported, with these additional features:

• You can merge cells horizontally by adding additional pipes (|) at the end of the cell.
• You can merge cells vertically by writing ^^ into a cell.
• You can merge the row below by writing \ at the end of a row.
• You can add a caption above or below to the table. Captions can optionally have labels.
• You can have a header with multiple rows.
• You can omit the header.
• You can divide the table into multiple sections by adding a single empty line in-between rows.

Differences to tables in DokuWiki

• You can use ^^ instead of ::: to merge cells vertically.
• You can merge the row below by writing \ at the end of a row.
• You can add a caption above or below to the table. Captions can optionally have labels.
• You can divide the table into multiple sections by adding a single empty line in-between rows.
• You cannot mix header cells (<th>) and ordinary cells (<td>) in a single row.
• You cannot independently align cells (only the whole column).

Built with...

• written in TypeScript
• Cheerio and htmlparser2 - for parsing HTML
• Turndown - for inline HTML to Markdown conversion
• Rollup - for bundling
• Mocha and Chai - for testing