Skip to content

Commit 599ae04

Browse files
committed
Add improved docs
1 parent 8c4c515 commit 599ae04

File tree

1 file changed

+90
-38
lines changed

1 file changed

+90
-38
lines changed

readme.md

+90-38
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ footnotes, strikethrough, tables, tasklists).
2020
* [API](#api)
2121
* [`gfmFromMarkdown()`](#gfmfrommarkdown)
2222
* [`gfmToMarkdown(options?)`](#gfmtomarkdownoptions)
23+
* [`Options`](#options)
24+
* [HTML](#html)
25+
* [Syntax](#syntax)
2326
* [Syntax tree](#syntax-tree)
2427
* [Types](#types)
2528
* [Compatibility](#compatibility)
@@ -29,17 +32,17 @@ footnotes, strikethrough, tables, tasklists).
2932

3033
## What is this?
3134

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]`),
3637
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).
3743

3844
## When to use this
3945

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-
4346
This project is useful when you want to support the same features that GitHub
4447
does in files in a repo, Gists, and several other places.
4548
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
4952
ways or even different than described in their spec, so *writing* in GFM is not
5053
always the best choice.
5154

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+
5261
Instead of this package, you can also use the extensions separately:
5362

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)
5564
— 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)
5766
— 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)
5968
— 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)
6170
— 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)
6372
— support GFM tasklists
6473

65-
When working with `mdast-util-from-markdown`, you must combine this package with
66-
[`micromark-extension-gfm`][extension].
67-
6874
A different utility, [`mdast-util-frontmatter`][mdast-util-frontmatter], adds
6975
support for frontmatter.
7076
GitHub supports YAML frontmatter for files in repos and Gists but they don’t
7177
treat it as part of GFM.
7278

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+
7383
This utility does not handle how markdown is turned to HTML.
7484
That’s done by [`mdast-util-to-hast`][mdast-util-to-hast].
7585
If your content is not in English, you should configure that utility.
7686

7787
## Install
7888

7989
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][]:
8191

8292
```sh
8393
npm install mdast-util-gfm
@@ -301,65 +311,97 @@ A note[^1]
301311

302312
## API
303313

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].
305316
There is no default export.
306317

307318
### `gfmFromMarkdown()`
308319

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]).
311327

312328
### `gfmToMarkdown(options?)`
313329

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`
316344

317-
##### `options`
345+
Configuration (TypeScript type).
318346

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].
322365

323366
## Syntax tree
324367

325368
This utility combines several mdast utilities.
326369
See their readmes for the node types supported in the tree:
327370

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)
329372
— 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)
331374
— 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)
333376
— 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)
335378
— 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)
337380
— GFM tasklists
338381

339382
## Types
340383

341384
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].
344386

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`.
347389

348390
## Compatibility
349391

350392
Projects maintained by the unified collective are compatible with all maintained
351393
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+.
353395
Our projects sometimes work with older versions, but this is not guaranteed.
354396

355397
This plugin works with `mdast-util-from-markdown` version 1+ and
356398
`mdast-util-to-markdown` version 1+.
357399

358400
## Related
359401

360-
* [`remarkjs/remark-gfm`][remark-gfm]
402+
* [`remark-gfm`][remark-gfm]
361403
— remark plugin to support GFM
362-
* [`micromark/micromark-extension-gfm`][extension]
404+
* [`micromark-extension-gfm`][extension]
363405
— micromark extension to parse GFM
364406

365407
## Contribute
@@ -430,14 +472,24 @@ abide by its terms.
430472

431473
[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
432474

475+
[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension
476+
433477
[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown
434478

479+
[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options
480+
435481
[mdast-util-frontmatter]: https://github.com/syntax-tree/mdast-util-frontmatter
436482

437483
[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast
438484

439485
[extension]: https://github.com/micromark/micromark-extension-gfm
440486

441-
[table]: https://github.com/syntax-tree/mdast-util-gfm-table#options
487+
[syntax]: https://github.com/micromark/micromark-extension-gfm#syntax
442488

443489
[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

Comments
 (0)