{"id":13339507,"url":"https://github.com/adobe/mdast-util-gridtables","last_synced_at":"2026-01-24T20:44:29.909Z","repository":{"id":61074304,"uuid":"539901942","full_name":"adobe/mdast-util-gridtables","owner":"adobe","description":"mdast extension to parse and serialize gridtables","archived":false,"fork":false,"pushed_at":"2024-10-19T15:56:14.000Z","size":917,"stargazers_count":1,"open_issues_count":1,"forks_count":3,"subscribers_count":18,"default_branch":"main","last_synced_at":"2024-10-25T09:44:52.784Z","etag":null,"topics":["helix","library","markdown","mdast","mdast-util","unist"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adobe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-22T09:30:12.000Z","updated_at":"2024-10-19T15:56:15.000Z","dependencies_parsed_at":"2023-02-15T17:31:12.653Z","dependency_job_id":"f79abfd8-078a-4062-a8df-3b34be5a3c2f","html_url":"https://github.com/adobe/mdast-util-gridtables","commit_stats":{"total_commits":40,"total_committers":5,"mean_commits":8.0,"dds":0.475,"last_synced_commit":"7e042f874a336bed6c1252c8ac27887b14be8e78"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Fmdast-util-gridtables","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Fmdast-util-gridtables/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Fmdast-util-gridtables/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adobe%2Fmdast-util-gridtables/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adobe","download_url":"https://codeload.github.com/adobe/mdast-util-gridtables/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243051878,"owners_count":20228284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["helix","library","markdown","mdast","mdast-util","unist"],"created_at":"2024-07-29T19:20:04.343Z","updated_at":"2025-11-30T12:04:40.899Z","avatar_url":"https://github.com/adobe.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MDAST Util Gridtables\n\n\u003e Mdast utility that serializes gridtables to mdast and/or hast.\n\n## Status\n[![codecov](https://img.shields.io/codecov/c/github/adobe/mdast-util-gridtables.svg)](https://codecov.io/gh/adobe/mdast-util-gridtables)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/adobe/mdast-util-gridtables/main.yaml)\n[![GitHub license](https://img.shields.io/github/license/adobe/mdast-util-gridtables.svg)](https://github.com/adobe/mdast-util-gridtables/blob/master/LICENSE.txt)\n[![GitHub issues](https://img.shields.io/github/issues/adobe/mdast-util-gridtables.svg)](https://github.com/adobe/mdast-util-gridtables/issues)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n\n## What is this?\n\nThis package contains extensions that add support for the grid table syntax \nto [`mdast-util-from-markdown`][mdast-util-from-markdown] \nand [`mdast-util-to-markdown`][mdast-util-to-markdown].\n\n## When to use this\n\nThese tools are all rather low-level.\nIn most cases, you’d want to use [`@adobe/remark-gridtables`][remark-gridtables] with remark instead.\n\nWhen working with `mdast-util-from-markdown`, you must combine this package with\n[`@adobe/micromark-extension-gridtables`][extension].\n\nThis utility does not handle how markdown is turned to HTML.\nThat’s done by [`mdast-util-to-hast`][mdast-util-to-hast].\n\n## Install\n\nThis package is [ESM only][esm].\nIn Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:\n\n```sh\nnpm install @adobe/mdast-util-gridtables\n```\n\n## Usage\n\nNote: due to the architecture of the micromark parser, it is not possible to parse the cell contents\ncontinuously. Furthermore, the to-markdown utility doesn't make its configuration available to\nextensions, so we need to pass the configuration manually into the gridtables extension.\n\n```js\nimport fs from 'node:fs/promises';\nimport { fromMarkdown } from 'mdast-util-from-markdown';\nimport { toMarkdown } from 'mdast-util-to-markdown';\nimport { gridTables } from '@adobe/micromark-extension-gridtables'\nimport { \n  gridTablesToMarkdown, \n  gridTablesFromMarkdown, \n  mdast2hastGridTablesHandler,\n  TYPE_TABLE,\n} from '@adobe/mdast-util-gridtables';\n\nconst doc = await fs.readFile('example.md')\n\n// convert markdown to mdast\nconst options = {\n  extensions: [gridTables],\n  mdastExtensions: [],\n};\noptions.mdastExtensions.push(gridTablesFromMarkdown(options));\nconst tree = fromMarkdown(sourceMarkdown, options);\n\n// convert mdast to md\nconst outputMarkdown = toMarkdown(tree, {extensions: [gridTablesToMarkdown()]})\n\n// convert mdast to hast\nconst hast = mdast2hast(mdast, {\n  handlers: {\n    [TYPE_TABLE]: mdast2hastGridTablesHandler(),\n  },\n});\n```\n\nAlso see a working [example](/example/index.js).\n\n## Overview\n\nGridTables look like this:\n\n```\n+-------------------+------+\n| Table Headings    | Here |\n+--------+----------+------+\n| Sub    | Headings | Too  |\n+========+=================+\n| cell   | column spanning |\n| spans  +---------:+------+\n| rows   |   normal | cell |\n+---v----+:---------------:+\n|        | cells can be    |\n|        | *formatted*     |\n|        | **paragraphs**  |\n|        | ```             |\n| multi  | and contain     |\n| line   | blocks          |\n| cells  | ```             |\n+========+=========\u003c+======+\n| footer |    cells |      |\n+--------+----------+------+\n```\n\n- the top of a cell must be indicated by `+-` followed by some `-` or `+` and finished by `-+`.\n- if the table contains a footer but no header, the top row should use `=` as grid line.\n- col spans are indicated by missing column (`|`) delimiters\n- row spans are indicated by missing row (`-`) delimiters\n- cells can be left, center, right, or justify aligned; indicated by the placement of `:` or `\u003e\u003c`\n- cells can be top, middle, or bottom v-aligned; indicated by the placement of arrows (`v` `^` `x`)\n- the header and footer sections are delimited by section delimiters (`=`).\n- if no section delimiters are present, all cells are placed in the table body.\n- if only 1 section delimiter is present, it delimits header from body.\n- the content in cells can be a full Markdown document again. note, that the cell boundaries (`|`)\n  need to exactly match with the column markers (`+`) in the row delimiters, if the cell content\n  contains `|`, otherwise the correct layout of the table can't be guaranteed.\n\nLayout\n======\n\nThe table layout tries to keep the table within a certain width (default 120). For example,\nif the table has 3 columns, each column will be max 40 characters wide. If all text in a column\nis smaller, it will shrink the columns. However, cells have a minimum width (default 10) when\ntext needs to be broken. If the cell contents need more space, e.g. with a nested table or\ncode block, it will grow accordingly.\n\nAlign\n=====\n\nHorizontal align is indicated by placing markers at the grid line above the cell:\n\n```\nJustify     Center     Left       Right\n+\u003e-----\u003c+  +:-----:+  +:------+  +------:+\n| A b C |  |  ABC  |  | ABC   |  |   ABC |\n+-------+  +-------+  +-------+  +-------+\n```\n\nVertical align is indicated by placing markers at the center of the grid line above the cell:\n\n```\nTop        Middle     Bottom\n+---^---+  +---x---+  +---v---+\n| Larum |  |       |  |       |\n| Ipsum |  | Larum |  |       |\n|       |  | Ipsum |  | Larum |\n|       |  |       |  | Ipsum |\n+-------+  +-------+  +-------+\n```\n\n## Syntax\n\n```ebfn\n\ngridTable := gridLine cellLine+ gridLine;\ngridLine := gridCell+ \"+\";\ncellLine := ( gridCell | cellContent )+ ( \"+\" | \"|\" );   \ngridCell := \"+\" alignMarkerStart? (\"-\" | \"=\")+ vAlignMarker? (\"-\" | \"=\")* alignMarkerEnd?;\ncellContent := ( \"+\" | \"|\" ) \" \" content \" \" ;\nalignMarkerStart := \":\" | \"\u003e\";\nalignMarkerEnd   := \":\" | \"\u003c\";\nvAlignMarker     := \"^\" | \"v\" | \"x\"\n```\n\n## MDAST Syntax tree\n\nThe following interfaces are added to **[mdast][]** by this utility.\n\n### Nodes\n\n#### `GridTable`\n\n```idl\ninterface GridTable \u003c: Parent {\n  type: \"gridTable\"\n  children: [GridTableHeader|GridTableBody|GridTableFooter]\n}\n```\n\n#### `GridTableHeader`\n\n```idl\ninterface GridTableHeader \u003c: Parent {\n  type: \"gtHead\"\n  children: [GridTableRow]\n}\n```\n\n#### `GridTableBody`\n\n```idl\ninterface GridTableBody \u003c: Parent {\n  type: \"gtBody\"\n  children: [GridTableRow]\n}\n```\n\n#### `GridTableFoot`\n\n```idl\ninterface GridTableFooter \u003c: Parent {\n  type: \"gtFoot\"\n  children: [GridTableRow]\n}\n```\n\n#### `GridTableRow`\n\n```idl\ninterface GridTableRow \u003c: Parent {\n  type: \"gtRow\"\n  children: [GridTableCell]\n}\n```\n\n#### `GridTableCell`\n\n```idl\ninterface GridTableCell \u003c: Parent {\n  type: \"gtCell\"\n  colSpan: number \u003e= 1\n  rowSpan: number \u003e= 1\n  align: alignType\n  valign: valignType\n  children: [MdastContent]\n}\n```\n\n**GridTableCell** ([**Parent**][dfn-parent]) represents a header cell in a\n[**GridTable**][dfn-table], if its parent is a [*gridTableHead*][term-head], or a data\ncell otherwise.\n\n**GridTableCell** can be used where [**gridTableRow**][dfn-row-content] content is expected.\nIts content model is [**mdast**][dfn-phrasing-content] content, allowing full mdast documents.\n\n### Enumeration\n\n#### `alignType`\n\n```idl\nenum alignType {\n  \"left\" | \"right\" | \"center\" | \"justify\" | null\n}\n```\n\n#### `valignType`\n\n```idl\nenum alignType {\n  \"top\" | \"bottom\" | \"middle\" | null\n}\n```\n\n\n\n\n\n\n\n\n\u003c!-- Definitions --\u003e\n\n[npm]: https://docs.npmjs.com/cli/install\n\n[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n\n[remark-gfm]: https://github.com/remarkjs/remark-gfm\n\n[mdast]: https://github.com/syntax-tree/mdast\n\n[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown\n\n[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown\n\n[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast\n\n[extension]: https://github.com/@adobe/micromark-extension-gridtables\n\n[dfn-parent]: https://github.com/syntax-tree/mdast#parent\n\n[dfn-phrasing-content]: https://github.com/syntax-tree/mdast#phrasingcontent\n\n[dfn-break]: https://github.com/syntax-tree/mdast#break\n\n[dfn-flow-content]: #flowcontent-gfm-table\n\n[dfn-table-content]: #tablecontent\n\n[dfn-enum-align-type]: #aligntype\n\n[dfn-row-content]: #rowcontent\n\n[dfn-table]: #table\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadobe%2Fmdast-util-gridtables","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadobe%2Fmdast-util-gridtables","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadobe%2Fmdast-util-gridtables/lists"}