@yozora/tokenizer-table
GFM enables the table extension, where an additional leaf block type is available.
A table is an arrangement of data with rows and columns, consisting of a single header row, a delimiter row separating the header from the data, and zero or more data rows.
Each row consists of cells containing arbitrary text, in which inlines
are parsed, separated by pipes (|
). A leading and trailing pipe is also
recommended for clarity of reading, and if there’s otherwise parsing ambiguity.
Spaces between pipes and cell content are trimmed. Block-level elements cannot
be inserted in a table.
The delimiter row consists of cells whose only content are hyphens (-
), and
optionally, a leading or trailing colon (:
), or both, to indicate left, right,
or center alignment respectively.
- See github flavor markdown spec for details.
- See Live Examples for an intuitive impression.
Install
- npm
- Yarn
- pnpm
npm install --save @yozora/tokenizer-table
yarn add @yozora/tokenizer-table
pnpm add @yozora/tokenizer-table
Usage
@yozora/tokenizer-table has been integrated into @yozora/parser / @yozora/parser-gfm-ex,
so you can use YozoraParser
/ GfmExParser
directly.
- Basic Usage
- YozoraParser
- GfmParser
- GfmExParser
@yozora/tokenizer-table cannot be used alone, it needs to be registered in YastParser as a plugin-in before it can be used.
import { DefaultYastParser } from '@yozora/core-parser'
import ParagraphTokenizer from '@yozora/tokenizer-paragraph'
import TextTokenizer from '@yozora/tokenizer-text'
import TableTokenizer from '@yozora/tokenizer-table'
const parser = new DefaultYastParser()
.useBlockFallbackTokenizer(new ParagraphTokenizer())
.useInlineFallbackTokenizer(new TextTokenizer())
.useTokenizer(new TableTokenizer())
// parse source markdown content
parser.parse(`
| foo | bar |
| --- | --- |
| baz | bim |
`)
import YozoraParser from '@yozora/parser'
const parser = new YozoraParser()
// parse source markdown content
parser.parse(`
| foo | bar |
| --- | --- |
| baz | bim |
`)
import GfmParser from '@yozora/parser-gfm'
import TableTokenizer from '@yozora/tokenizer-table'
const parser = new GfmParser()
parser.useTokenizer(new TableTokenizer())
// parse source markdown content
parser.parse(`
| foo | bar |
| --- | --- |
| baz | bim |
`)
import GfmExParser from '@yozora/parser-gfm-ex'
const parser = new GfmExParser()
// parse source markdown content
parser.parse(`
| foo | bar |
| --- | --- |
| baz | bim |
`)
Options
Name | Type | Required | Default |
---|---|---|---|
name | string | false | "@yozora/tokenizer-table" |
priority | number | false | TokenizerPriority.INTERRUPTABLE_BLOCK |
-
name
: The unique name of the tokenizer, used to bind the token it generates, to determine the tokenizer that should be called in each life cycle of the token in the entire matching / parsing phase. -
priority
: Priority of the tokenizer, determine the order of processing, high priority priority execution. interruptable. In addition, in thematch-block
stage, a high-priority tokenizer can interrupt the matching process of a low-priority tokenizer.
Types
@yozora/tokenizer-table produce Table / TableRow / TableCell type nodes. See @yozora/ast for full base types.
-
TableCell
import type { YastParent } from '@yozora/ast'
export const TableCellType = 'tableCell'
export type TableCellType = typeof TableCellType
/**
* TableCell represents a header cell in a Table, if its parent is a head,
* or a data cell otherwise.
* @see https://github.com/syntax-tree/mdast#tablecell
* @see https://github.github.com/gfm/#tables-extension-
*/
export type TableCell = YastParent<TableCellType> -
TableRow
import type { YastParent } from '@yozora/ast'
export const TableRowType = 'tableRow'
export type TableRowType = typeof TableRowType
/**
* TableRow represents a row of cells in a table.
* @see https://github.com/syntax-tree/mdast#tablerow
* @see https://github.github.com/gfm/#tables-extension-
*/
export interface TableRow extends YastParent<TableRowType> {
/**
* Table cells
*/
children: TableCell[]
} -
Table
import type { YastAlignType, YastParent } from '@yozora/ast'
export const TableType = 'table'
export type TableType = typeof TableType
/**
* Table column configs.
*/
export interface TableColumn {
/**
* An align field can be present. If present, it must be a list of alignTypes.
* It represents how cells in columns are aligned.
*/
align: YastAlignType
}
/**
* @see https://github.github.com/gfm/#table
* @see https://github.com/syntax-tree/mdast#table
*/
export interface Table extends YastParent<TableType> {
/**
* Table column configuration items
*/
columns: TableColumn[]
/**
* Table rows (include table headers)
*/
children: TableRow[]
}
Live Examples
-
Basic.
-
Cells in one column don’t need to match length, though it’s easier to read if they are. Likewise, use of leading and trailing pipes may be inconsistent.
-
Include a pipe in a cell’s content by escaping it, including inside other inline spans.
-
The table is broken at the first empty line, or beginning of another block-level structure.
-
The header row must match the delimiter row in the number of cells. If not, a table will not be recognized.
-
The remainder of the table’s rows may vary in the number of cells. If there are a number of cells fewer than the number of cells in the header row, empty cells are inserted. If there are greater, the excess is ignored.
-
If there are no rows in the body, no
<tbody>
is generated in HTML output.