@@ -20,6 +20,9 @@ footnotes, strikethrough, tables, tasklists).
20
20
* [ API] ( #api )
21
21
* [ ` gfmFromMarkdown() ` ] ( #gfmfrommarkdown )
22
22
* [ ` gfmToMarkdown(options?) ` ] ( #gfmtomarkdownoptions )
23
+ * [ ` Options ` ] ( #options )
24
+ * [ HTML] ( #html )
25
+ * [ Syntax] ( #syntax )
23
26
* [ Syntax tree] ( #syntax-tree )
24
27
* [ Types] ( #types )
25
28
* [ Compatibility] ( #compatibility )
@@ -29,17 +32,17 @@ footnotes, strikethrough, tables, tasklists).
29
32
30
33
## What is this?
31
34
32
- This package contains extensions for
33
- [ ` mdast-util-from-markdown ` ] [ mdast-util-from-markdown ] and
34
- [ ` mdast-util-to-markdown ` ] [ mdast-util-to-markdown ] to enable the features that
35
- GitHub adds to markdown: autolink literals (` www.x.com ` ), footnotes (` [^1] ` ),
35
+ This package contains two extensions that add support for GFM syntax in
36
+ markdown to [ mdast] [ ] : : autolink literals (` www.x.com ` ), footnotes (` [^1] ` ),
36
37
strikethrough (` ~~stuff~~ ` ), tables (` | cell |… ` ), and tasklists (` * [x] ` ).
38
+ These extensions plug into
39
+ [ ` mdast-util-from-markdown ` ] [ mdast-util-from-markdown ] (to support parsing
40
+ GFM in markdown into a syntax tree) and
41
+ [ ` mdast-util-to-markdown ` ] [ mdast-util-to-markdown ] (to support serializing
42
+ GFM in syntax trees to markdown).
37
43
38
44
## When to use this
39
45
40
- These tools are all rather low-level.
41
- In many cases, you’d want to use [ ` remark-gfm ` ] [ remark-gfm ] with remark instead.
42
-
43
46
This project is useful when you want to support the same features that GitHub
44
47
does in files in a repo, Gists, and several other places.
45
48
Users frequently believe that some of these extensions, specifically autolink
@@ -49,35 +52,42 @@ There are several edge cases where GitHub’s implementation works in unexpected
49
52
ways or even different than described in their spec, so * writing* in GFM is not
50
53
always the best choice.
51
54
55
+ You can use these extensions when you are working with
56
+ ` mdast-util-from-markdown ` and ` mdast-util-to-markdown ` already.
57
+
58
+ When working with ` mdast-util-from-markdown ` , you must combine this package
59
+ with [ ` micromark-extension-gfm ` ] [ extension ] .
60
+
52
61
Instead of this package, you can also use the extensions separately:
53
62
54
- * [ ` syntax-tree/ mdast-util-gfm-autolink-literal` ] ( https://github.com/syntax-tree/mdast-util-gfm-autolink-literal )
63
+ * [ ` mdast-util-gfm-autolink-literal ` ] ( https://github.com/syntax-tree/mdast-util-gfm-autolink-literal )
55
64
— support GFM autolink literals
56
- * [ ` syntax-tree/ mdast-util-gfm-footnote` ] ( https://github.com/syntax-tree/mdast-util-gfm-footnote )
65
+ * [ ` mdast-util-gfm-footnote ` ] ( https://github.com/syntax-tree/mdast-util-gfm-footnote )
57
66
— support GFM footnotes
58
- * [ ` syntax-tree/ mdast-util-gfm-strikethrough` ] ( https://github.com/syntax-tree/mdast-util-gfm-strikethrough )
67
+ * [ ` mdast-util-gfm-strikethrough ` ] ( https://github.com/syntax-tree/mdast-util-gfm-strikethrough )
59
68
— support GFM strikethrough
60
- * [ ` syntax-tree/ mdast-util-gfm-table` ] ( https://github.com/syntax-tree/mdast-util-gfm-table )
69
+ * [ ` mdast-util-gfm-table ` ] ( https://github.com/syntax-tree/mdast-util-gfm-table )
61
70
— support GFM tables
62
- * [ ` syntax-tree/ mdast-util-gfm-task-list-item` ] ( https://github.com/syntax-tree/mdast-util-gfm-task-list-item )
71
+ * [ ` mdast-util-gfm-task-list-item ` ] ( https://github.com/syntax-tree/mdast-util-gfm-task-list-item )
63
72
— support GFM tasklists
64
73
65
- When working with ` mdast-util-from-markdown ` , you must combine this package with
66
- [ ` micromark-extension-gfm ` ] [ extension ] .
67
-
68
74
A different utility, [ ` mdast-util-frontmatter ` ] [ mdast-util-frontmatter ] , adds
69
75
support for frontmatter.
70
76
GitHub supports YAML frontmatter for files in repos and Gists but they don’t
71
77
treat it as part of GFM.
72
78
79
+ All these packages are used in [ ` remark-gfm ` ] [ remark-gfm ] , which
80
+ focusses on making it easier to transform content by abstracting these
81
+ internals away.
82
+
73
83
This utility does not handle how markdown is turned to HTML.
74
84
That’s done by [ ` mdast-util-to-hast ` ] [ mdast-util-to-hast ] .
75
85
If your content is not in English, you should configure that utility.
76
86
77
87
## Install
78
88
79
89
This package is [ ESM only] [ esm ] .
80
- In Node.js (version 12.20+, 14.14+, or 16.0+), install with [ npm] [ ] :
90
+ In Node.js (version 14.14+ and 16.0+), install with [ npm] [ ] :
81
91
82
92
``` sh
83
93
npm install mdast-util-gfm
@@ -301,65 +311,97 @@ A note[^1]
301
311
302
312
## API
303
313
304
- This package exports the identifiers ` gfmFromMarkdown ` and ` gfmToMarkdown ` .
314
+ This package exports the identifiers [ ` gfmFromMarkdown ` ] [ api-gfm-from-markdown ]
315
+ and [ ` gfmToMarkdown ` ] [ api-gfm-to-markdown ] .
305
316
There is no default export.
306
317
307
318
### ` gfmFromMarkdown() `
308
319
309
- Function that can be called to get an extension for
310
- [ ` mdast-util-from-markdown ` ] [ mdast-util-from-markdown ] .
320
+ Create an extension for [ ` mdast-util-from-markdown ` ] [ mdast-util-from-markdown ]
321
+ to enable GFM (autolink literals, footnotes, strikethrough, tables, tasklists).
322
+
323
+ ###### Returns
324
+
325
+ Extension for ` mdast-util-from-markdown ` to enable GFM
326
+ ([ ` Array<FromMarkdownExtension> ` ] [ from-markdown-extension ] ).
311
327
312
328
### ` gfmToMarkdown(options?) `
313
329
314
- Function that can be called to get an extension for
315
- [ ` mdast-util-to-markdown ` ] [ mdast-util-to-markdown ] .
330
+ Create an extension for [ ` mdast-util-to-markdown ` ] [ mdast-util-to-markdown ]
331
+ to enable GFM (autolink literals, footnotes, strikethrough, tables, tasklists).
332
+
333
+ ###### Parameters
334
+
335
+ * ` options ` ([ ` Options ` ] [ api-options ] )
336
+ — configuration
337
+
338
+ ###### Returns
339
+
340
+ Extension for ` mdast-util-to-markdown ` to enable GFM
341
+ ([ ` Array<ToMarkdownExtension> ` ] [ to-markdown-extension ] ).
342
+
343
+ ### ` Options `
316
344
317
- ##### ` options `
345
+ Configuration (TypeScript type).
318
346
319
- Configuration (optional).
320
- Currently passes through ` tableCellPadding ` , ` tablePipeAlign ` , and
321
- ` stringLength ` to [ ` mdast-util-gfm-table ` ] [ table ] .
347
+ ###### Fields
348
+
349
+ * ` tableCellPadding ` (` boolean ` , default: ` true ` )
350
+ — whether to add a space of padding between delimiters and cells
351
+ * ` tablePipeAlign ` (` boolean ` , default: ` true ` )
352
+ — whether to align the delimiters
353
+ * ` stringLength ` (` ((value: string) => number) ` , default: ` s => s.length ` )
354
+ — function to detect the length of table cell content, used when aligning
355
+ the delimiters between cells
356
+
357
+ ## HTML
358
+
359
+ This utility does not handle how markdown is turned to HTML.
360
+ That’s done by [ ` mdast-util-to-hast ` ] [ mdast-util-to-hast ] .
361
+
362
+ ## Syntax
363
+
364
+ See [ Syntax in ` micromark-extension-gfm ` ] [ syntax ] .
322
365
323
366
## Syntax tree
324
367
325
368
This utility combines several mdast utilities.
326
369
See their readmes for the node types supported in the tree:
327
370
328
- * [ ` syntax-tree/ mdast-util-gfm-autolink-literal` ] ( https://github.com/syntax-tree/mdast-util-gfm-autolink-literal#syntax-tree )
371
+ * [ ` mdast-util-gfm-autolink-literal ` ] ( https://github.com/syntax-tree/mdast-util-gfm-autolink-literal#syntax-tree )
329
372
— GFM autolink literals
330
- * [ ` syntax-tree/ mdast-util-gfm-footnote` ] ( https://github.com/syntax-tree/mdast-util-gfm-footnote#syntax-tree )
373
+ * [ ` mdast-util-gfm-footnote ` ] ( https://github.com/syntax-tree/mdast-util-gfm-footnote#syntax-tree )
331
374
— GFM footnotes
332
- * [ ` syntax-tree/ mdast-util-gfm-strikethrough` ] ( https://github.com/syntax-tree/mdast-util-gfm-strikethrough#syntax-tree )
375
+ * [ ` mdast-util-gfm-strikethrough ` ] ( https://github.com/syntax-tree/mdast-util-gfm-strikethrough#syntax-tree )
333
376
— GFM strikethrough
334
- * [ ` syntax-tree/ mdast-util-gfm-table` ] ( https://github.com/syntax-tree/mdast-util-gfm-table#syntax-tree )
377
+ * [ ` mdast-util-gfm-table ` ] ( https://github.com/syntax-tree/mdast-util-gfm-table#syntax-tree )
335
378
— GFM tables
336
- * [ ` syntax-tree/ mdast-util-gfm-task-list-item` ] ( https://github.com/syntax-tree/mdast-util-gfm-task-list-item#syntax-tree )
379
+ * [ ` mdast-util-gfm-task-list-item ` ] ( https://github.com/syntax-tree/mdast-util-gfm-task-list-item#syntax-tree )
337
380
— GFM tasklists
338
381
339
382
## Types
340
383
341
384
This package is fully typed with [ TypeScript] [ ] .
342
- It exports an ` Options ` type, which specifies the interface of the accepted
343
- options.
385
+ It exports the additional type [ ` Options ` ] [ api-options ] .
344
386
345
- The ` Delete ` , ` FootnoteDefinition ` , ` FootnoteReference ` , ` Table ` , ` TableCell ` ,
346
- and ` TableRow ` node types are supported in ` @types/mdast ` by default .
387
+ The ` Delete ` , ` FootnoteDefinition ` , ` FootnoteReference ` , ` Table ` , ` TableRow ` ,
388
+ and ` TableCell ` types of the mdast nodes are exposed from ` @types/mdast ` .
347
389
348
390
## Compatibility
349
391
350
392
Projects maintained by the unified collective are compatible with all maintained
351
393
versions of Node.js.
352
- As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
394
+ As of now, that is Node.js 14.14+ and 16.0+.
353
395
Our projects sometimes work with older versions, but this is not guaranteed.
354
396
355
397
This plugin works with ` mdast-util-from-markdown ` version 1+ and
356
398
` mdast-util-to-markdown ` version 1+.
357
399
358
400
## Related
359
401
360
- * [ ` remarkjs/ remark-gfm` ] [ remark-gfm ]
402
+ * [ ` remark-gfm ` ] [ remark-gfm ]
361
403
— remark plugin to support GFM
362
- * [ ` micromark/micromark -extension-gfm ` ] [ extension ]
404
+ * [ ` micromark-extension-gfm ` ] [ extension ]
363
405
— micromark extension to parse GFM
364
406
365
407
## Contribute
@@ -430,14 +472,24 @@ abide by its terms.
430
472
431
473
[ mdast-util-from-markdown ] : https://github.com/syntax-tree/mdast-util-from-markdown
432
474
475
+ [ from-markdown-extension ] : https://github.com/syntax-tree/mdast-util-from-markdown#extension
476
+
433
477
[ mdast-util-to-markdown ] : https://github.com/syntax-tree/mdast-util-to-markdown
434
478
479
+ [ to-markdown-extension ] : https://github.com/syntax-tree/mdast-util-to-markdown#options
480
+
435
481
[ mdast-util-frontmatter ] : https://github.com/syntax-tree/mdast-util-frontmatter
436
482
437
483
[ mdast-util-to-hast ] : https://github.com/syntax-tree/mdast-util-to-hast
438
484
439
485
[ extension ] : https://github.com/micromark/micromark-extension-gfm
440
486
441
- [ table ] : https://github.com/syntax-tree/mdast-util -gfm-table#options
487
+ [ syntax ] : https://github.com/micromark/micromark-extension -gfm#syntax
442
488
443
489
[ gfm ] : https://github.github.com/gfm/
490
+
491
+ [ api-gfm-from-markdown ] : #gfmfrommarkdown
492
+
493
+ [ api-gfm-to-markdown ] : #gfmtomarkdownoptions
494
+
495
+ [ api-options ] : #options
0 commit comments