https://github.com/posthtml/posthtml-toc
📑Table of contents
https://github.com/posthtml/posthtml-toc
Last synced: 10 months ago
JSON representation
📑Table of contents
- Host: GitHub
- URL: https://github.com/posthtml/posthtml-toc
- Owner: posthtml
- License: mit
- Created: 2020-05-23T10:10:08.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-03-04T19:59:24.000Z (almost 3 years ago)
- Last Synced: 2024-10-29T21:06:08.269Z (over 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 786 KB
- Stars: 4
- Watchers: 4
- Forks: 3
- Open Issues: 5
-
Metadata Files:
- Readme: readme.md
- Contributing: contributing.md
- License: license
Awesome Lists containing this project
README
# PostHTML TOC 
[![NPM][npm]][npm-url]
[![Standard Code Style][style]][style-url]
> A table of contents, usually headed simply Contents and abbreviated informally as TOC, is a list, usually found on a page before the start of a written work, of its chapter or section titles or brief descriptions with their commencing page numbers. [Wikipedia](https://en.wikipedia.org/wiki/Table_of_contents)
The plugin works particularly well with markdown documents.
By defaults
Before:
``` html
Title 1
p1
Title 2
p2
Title 3
p3
```
After:
``` html
Title 1
p1
Title 2
p2
Title 3
p3
```
## Install
Installation in your project
```npm i posthtml posthtml-toc```
## Usage
``` js
const fs = require('fs');
const posthtml = require('posthtml');
const toc = require('posthtml-toc');
posthtml()
.use(toc({ /* options */ }))
.process(html/*, options */)
.then(result => fs.writeFileSync('./after.html', result.html));
```
## Options
Defaults options
* `insert = { after: 'h1' }` — insert the TOC immediately after the first `
`
* `title = "Content"` — Title TOC block
* `ignoreMissingSelector = false` — throw an error if the selector is not found
* `ignoreMissingHeadings = false` — throw an error if the no headings are found
* `toggle` is undefined
### `insert` option
This option allows you to specify where the TOC will be inserted in the HTML
output. The option expects an object with **exactly one key** with a string
value, as in this schema:
```
{ insert: { : } }
```
`` is a string used to select an HTML element by matching one of three
patterns:
* `''` — matches the first element with the name ``.
_Example_: `'nav'` matches ``.
* `'#'` — matches the first element with `` as the `id` attribute value.
_Example_: `'#here'` matches `
`.
* `'.'` — matches the first element with `` as one of the
space-separated strings in the `class` attribute value.
_Example_: `'.here'` matches `
`.
`` can be one of the following:
* `after` — The TOC will be inserted immediately after the matching node.
_Example_: `{ insert: { after: 'h1' } }` (_default_) produces:
```diff
...
+...
...
```
* `before` — The TOC will be inserted immediately before the matching node.
_Example_: `{ insert: { before: '#here' } }` produces:
```diff
...
+...
...
```
* `afterChildren` — The TOC will be inserted into the contents of the matching
node after the last child.
_Example_: `{ insert: { afterChildren: '.here' } }` produces:
```diff
...
+ ...
```
* `beforeChildren` — The TOC will be inserted into the contents of the matching
node before the first child.
_Example_: `{ insert: { beforeChildren: '.here' } }` produces:
```diff
+
...
...
```
### `toggle` options
Before:
``` html
Title 1
p1
Title 2
p2
Title 3
p3
```
Add option:
``` js
const fs = require('fs');
const posthtml = require('posthtml');
const toc = require('posthtml-toc');
posthtml()
.use(toc({
toggle: ['show', 'hide', true]
}))
.process(html/*, options */)
.then(result => fs.writeFileSync('./after.html', result.html));
```
After:
``` html
Title 1
#toctoggle,#toctoggle:checked~ul{display:none}
#toctoggle~label:after{content:"hide"}
#toctoggle:checked~label:after{content:"show"}
#toc label{cursor:pointer}
p1
Title 2
p2
Title 3
p3
```
### `ignoreMissingSelector` option
* `{ ignoreMissingSelector: false }` (_default_) — throw an error if the
selector (the default `h1` tag or the value passed to `options.after`) is not
found.
For example, with this option, you get an error on the second file because
there is no `h1` tag:
```html
Title 1
Title 2
```
```html
```
* `{ ignoreMissingSelector: true }` — ignore HTML input that does not have
the selector.
This is useful if you want to uniformly process a number of files but don't
want to insert a TOC in all of them.
For example, with the files mentioned above, instead of an error, the first
file is modified and the second file is unchanged:
```html
Title 1
Title 2
```
```html
```
### `ignoreMissingHeadings` option
This option controls what happens when no headings (`h2`, `h3`, `h4`, `h5`,
`h6`) are found in the HTML input.
* `{ ignoreMissingHeadings: false }` (_default_) — throw an error if no headings
are found.
* `{ ignoreMissingHeadings: true }` — do not throw an error if no headings are
found. Instead, a TOC with an empty list (i.e. `
`) will be inserted.
### Contributing
See [PostHTML Guidelines](https://github.com/posthtml/posthtml/tree/master/docs) and [contribution guide](contributing.md).
### License [MIT](license)
[npm]: https://img.shields.io/npm/v/posthtml-toc.svg
[npm-url]: https://npmjs.com/package/posthtml-toc
[style]: https://img.shields.io/badge/code%20style-standard-yellow.svg
[style-url]: http://standardjs.com/