Skip to content

Commit

Permalink
Add improved docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@wooorm
wooorm committed Jan 25, 2023
1 parent 92f8a77 commit dbb8c51
Show file tree
Hide file tree
Showing 4 changed files with 96 additions and 90 deletions.
7 changes: 4 additions & 3 deletions lib/contents.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,13 @@
* @typedef ContentsOptions
* Build configuration.
* @property {boolean | null | undefined} [tight=false]
* Whether to compile list-items tightly.
* Whether to compile list items tightly.
* @property {boolean | null | undefined} [ordered=false]
* Whether to compile list-items as an ordered list, otherwise they are
* Whether to compile list items as an ordered list, otherwise they are
* unordered.
* @property {string | null | undefined} [prefix=null]
* @property {string | null | undefined} [prefix=undefined]
* Add a prefix to links to headings in the table of contents.
*
* Useful for example when later going from mdast to hast and sanitizing with
* `hast-util-sanitize`.
*/
Expand Down
12 changes: 9 additions & 3 deletions lib/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,17 @@
* @typedef Result
* Results.
* @property {number | null} index
* Where the contents section starts, if looking for a heading.
* Index of the node right after the table of contents heading, `-1` if no
* heading was found, `null` if no `heading` was given.
* @property {number | null} endIndex
* Where the contents section ends, if looking for a heading.
* Index of the first node after `heading` that is not part of its section,
* `-1` if no heading was found, `null` if no `heading` was given, same as
* `index` if there are no nodes between `heading` and the first heading in
* the table of contents.
* @property {List | null} map
* Built table of contents (`List`).
* List representing the generated table of contents, `null` if no table of
* contents could be created, either because no heading was found or because
* no following headings were found.
*/

import {search} from './search.js'
Expand Down
11 changes: 6 additions & 5 deletions lib/search.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,14 @@
/**
* @typedef SearchOptions
* Search configuration.
* @property {Rank | null | undefined} [maxDepth=6]
* Maximum heading depth to include in the table of contents.
*
* This is inclusive: when set to `3`, level three headings are included
* (those with three hashes, `###`).
* @property {string | null | undefined} [skip]
* Headings to skip, wrapped in `new RegExp('^(' + value + ')$', 'i')`.
*
* Any heading matching this expression will not be present in the table of
* contents.
* @property {Test} [parents]
Expand All @@ -25,11 +31,6 @@
*
* Internally, uses `unist-util-is` to check, so `parents` can be any
* `is`-compatible test.
* @property {Rank | null | undefined} [maxDepth=6]
* Maximum heading depth to include in the table of contents.
*
* This is inclusive: when set to `3`, level three headings are included
* (those with three hashes, `###`).
*
* @typedef SearchEntry
* Entry.
Expand Down
156 changes: 77 additions & 79 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,9 @@
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`toc(node[, options])`](#tocnode-options)
* [`toc(tree[, options])`](#toctree-options)
* [`Options`](#options)
* [`Result`](#result)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
Expand All @@ -40,7 +42,7 @@ This package is wrapped in [`remark-toc`][remark-toc] for ease of use with
## Install

This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
In Node.js (version 14.14+ and 16.0+), install with [npm][]:

```sh
npm install mdast-util-toc
Expand Down Expand Up @@ -105,12 +107,12 @@ Yields:

## API

This package exports the identifier `toc`.
This package exports the identifier [`toc`][api-toc].
There is no default export.

### `toc(node[, options])`
### `toc(tree[, options])`

Generate a table of contents from [`node`][node].
Generate a table of contents from `tree`.

Looks for the first heading matching `options.heading` (case insensitive) and
returns a table of contents (a list) for all following headings.
Expand All @@ -120,87 +122,77 @@ If no `heading` is specified, creates a table of contents for all headings in

Links in the list to headings are based on GitHub’s style.
Only top-level headings (those not in blockquotes or lists), are used.
This default behavior can be changed by passing [`options.parents`][parents].

##### `options`

Configuration (optional).

###### `options.heading`

[Heading][] to look for (`string`), wrapped in `new RegExp('^(' + value + ')$',
'i')`.

###### `options.maxDepth`

Maximum heading depth to include in the table of contents (`number`, default:
`6`),
This is inclusive: when set to `3`, level three headings are included (those
with three hashes, `###`).

###### `options.skip`

Headings to skip (`string`, optional), wrapped in
`new RegExp('^(' + value + ')$', 'i')`.
Any heading matching this expression will not be present in the table of
contents.

###### `options.tight`

Whether to compile list items tightly (`boolean?`, default: `false`).

###### `options.ordered`

Whether to compile list items as an ordered list (`boolean?`, default: `false`).

###### `options.prefix`

Add a prefix to links to headings in the table of contents (`string?`, default:
`null`).
Useful for example when later going from [mdast][] to [hast][] and sanitizing
with [`hast-util-sanitize`][sanitize].

###### `options.parents`

Allow headings to be children of certain node types (default: the to `toc` given
`node`, to only allow top-level headings).
Internally, uses [`unist-util-is`][is], so `parents` can be any
`is`-compatible test.

For example, the following code would allow headings under either `root` or
`blockquote` to be used:

```js
toc(tree, {parents: ['root', 'blockquote']})
```

##### Returns

An object representing the table of contents:

* `index` (`number?`)
— index of the node right after the table of contents [heading][].
`-1` if no heading was found, `null` if no `heading` was given
* `endIndex` (`number?`)
— index of the first node after `heading` that is not part of its section.
This default behavior can be changed by passing `options.parents`.

###### Parameters

* `tree` ([`Node`][node])
— tree to search and generate from
* `options` ([`Options`][api-options], optional)
— configuration

###### Returns

Results ([`Result`][api-result]).

### `Options`

Configuration (TypeScript type).

###### Fields

* `heading` (`string`, optional)
— heading to look for, wrapped in `new RegExp('^(' + value + ')$', 'i')`
* `maxDepth` (`number`, default: `6`)
— maximum heading depth to include in the table of contents.
This is inclusive: when set to `3`, level three headings are included
(those with three hashes, `###`)
* `skip` (`string`, optional)
— headings to skip, wrapped in `new RegExp('^(' + value + ')$', 'i')`.
Any heading matching this expression will not be present in the table of
contents
* `parents` ([`Test`][test], default: `tree`)
— allow headings to be children of certain node types.
Can by any [`unist-util-is`][is] compatible test
* `tight` (`boolean`, default: `false`)
— whether to compile list items tightly
* `ordered` (`boolean`, default: `false`)
— whether to compile list items as an ordered list, otherwise they are
unordered
* `prefix` (`string`, optional)
— add a prefix to links to headings in the table of contents.
Useful for example when later going from mdast to hast and sanitizing with
`hast-util-sanitize`.

### `Result`

Results (TypeScript type).

###### Fields

* `index` (`number` or `null`)
— index of the node right after the table of contents heading, `-1` if no
heading was found, `null` if no `heading` was given
* `endIndex` (`number` or `null`)
— index of the first node after `heading` that is not part of its section,
`-1` if no heading was found, `null` if no `heading` was given, same as
`index` if there are no nodes between `heading` and the first heading in the
table of contents
* `map` (`Node?`)
— list representing the generated table of contents.
`null` if no table of contents could be created, either because no heading
was found or because no following headings were found
`index` if there are no nodes between `heading` and the first heading in
the table of contents
* `map` ([`List`][list] or `null`)
— list representing the generated table of contents, `null` if no table of
contents could be created, either because no heading was found or because
no following headings were found

## Types

This package is fully typed with [TypeScript][].
It exports the types `Options` and `Result`.
It exports the types [`Options`][api-options] and [`Result`][api-result].

## Compatibility

Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
As of now, that is Node.js 14.14+ and 16.0+.
Our projects sometimes work with older versions, but this is not guaranteed.

## Security
Expand Down Expand Up @@ -313,14 +305,20 @@ abide by its terms.

[is]: https://github.com/syntax-tree/unist-util-is

[heading]: https://github.com/syntax-tree/mdast#heading
[list]: https://github.com/syntax-tree/mdast#list

[node]: https://github.com/syntax-tree/mdast#node

[parents]: #optionsparents

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

[remark]: https://github.com/remarkjs/remark

[remark-toc]: https://github.com/remarkjs/remark-toc

[test]: https://github.com/syntax-tree/unist-util-is#test

[api-toc]: #toctree-options

[api-options]: #options

[api-result]: #result

0 comments on commit dbb8c51

Please sign in to comment.