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 May 21, 2022
1 parent ba8f680 commit dac08a5
Show file tree
Hide file tree
Showing 3 changed files with 126 additions and 58 deletions.
5 changes: 4 additions & 1 deletion example.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,10 @@
import {inspect} from 'node:util'

// Dependencies:
/** @typedef {import('mdast').Root} Root */
/**
* @typedef {import('mdast').Root} Root
*/

import {u} from 'unist-builder'
import {toc} from './index.js'

Expand Down
12 changes: 11 additions & 1 deletion lib/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,17 @@ import {contents} from './contents.js'
import {toExpression} from './to-expression.js'

/**
* Get a TOC representation of `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.
* If no `heading` is specified, creates a table of contents for all headings in
* `tree`.
* `tree` is not changed.
*
* 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`.
*
* @param {Node} node
* @param {Options} [options]
Expand Down
167 changes: 111 additions & 56 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,67 @@
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[**mdast**][mdast] utility to generate table of contents.
[mdast][] utility to generate a table of contents.

## Install
## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`toc(node[, options])`](#tocnode-options)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This package is a utility that generates a table of contents from a document.

This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
## When should I use this?

This utility is useful to generate a section so users can more easily navigate
through a document.

This package is wrapped in [`remark-toc`][remark-toc] for ease of use with
[remark][], where it also injects the table of contents into the document.

## Install

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

```sh
npm install mdast-util-toc
```

In Deno with [`esm.sh`][esmsh]:

```js
import {toc} from 'https://esm.sh/mdast-util-toc@6'
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
import {toc} from 'https://esm.sh/mdast-util-toc@6?bundle'
</script>
```

## Use

Dependencies:

```javascript
/** @typedef {import('mdast').Root} Root */
/**
* @typedef {import('mdast').Root} Root
*/

import {u} from 'unist-builder'
import {toc} from 'mdast-util-toc'
```
Expand Down Expand Up @@ -63,25 +105,27 @@ Yields:

## API

This package exports the following identifiers: `toc`.
This package exports the identifier `toc`.
There is no default export.

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

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

Looks for the first [heading][] matching `options.heading` (case insensitive),
and returns a table of contents ([list][]) for all following headings.
Looks for the first heading matching `options.heading` (case insensitive) and
returns a table of contents (a list) for all following headings.
If no `heading` is specified, creates a table of contents for all headings in
`tree`.
`tree` is not changed.

Links to headings are based on GitHub’s style.
Only top-level headings (those not in [blockquote][]s or [list][]s), are used.
This default behavior can be changed by passing [`parents`][parents].
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 + ')$',
Expand All @@ -103,58 +147,66 @@ contents.

###### `options.tight`

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

###### `options.ordered`

Whether to compile list-items as an ordered list (`boolean?`, default: `false`).
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`).
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`

Allows headings to be children of certain node [type][]s (default: the to `toc`
given `tree`, to only allow top-level headings).
Internally, uses [unist-util-is][is] to check, so `parents` can be any
[`is`-compatible][is] test.
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, this would allow headings under either `root` or `blockquote` to be
used:
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.

###### Properties
An object representing the table of contents:

* `index` (`number?`)
— [Index][] of the node right after the table of contents [heading][].
— 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.
`-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 TOC
— 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
— 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`.

## 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+.
Our projects sometimes work with older versions, but this is not guaranteed.

## Security

Use of `mdast-util-toc` does not involve [**hast**][hast], user content, or
change the tree, so there are no openings for [cross-site scripting (XSS)][xss]
attacks.
Use of `mdast-util-toc` does not involve [hast][], user content, or change the
tree, so there are no openings for [cross-site scripting (XSS)][xss] attacks.

Injecting `map` into the syntax tree may open you up to XSS attacks as existing
nodes are copied into the table of contents.
Expand All @@ -180,22 +232,21 @@ Yields in `map`:
- [Charlie](#charlie)
```

Always use [`hast-util-santize`][sanitize] when transforming to
[**hast**][hast].
Always use [`hast-util-santize`][sanitize] when transforming to [hast][].

## Related

* [`github-slugger`](https://github.com/Flet/github-slugger)
— Generate a slug just like GitHub does
— generate a slug just like GitHub does
* [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit)
— visit nodes
* [`unist-util-visit-parents`](https://github.com/syntax-tree/unist-util-visit-parents)
— like `visit`, but with a stack of parents

## Contribute

See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
started.
See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [code of conduct][coc].
Expand Down Expand Up @@ -236,15 +287,23 @@ abide by its terms.

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://barrythepenguin.github.io

[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

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

Expand All @@ -254,18 +313,14 @@ abide by its terms.

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

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

[type]: https://github.com/syntax-tree/unist#type

[index]: https://github.com/syntax-tree/unist#index

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

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

[blockquote]: https://github.com/syntax-tree/mdast#blockquote
[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

0 comments on commit dac08a5

Please sign in to comment.