hast utility to change heading rank (or depth, level)
npm install hast-util-shift-heading[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]
[hast][] utility to change ranks (also knows as depth or level) of headings.
* What is this?
* When should I use this?
* Install
* Use
* API
* shiftHeading(tree, shift)
* Types
* Compatibility
* Security
* Related
* Contribute
* License
This package is a small utility that rewrites heading ranks relative to a
number.
You can use this package when you have some content, say an article that starts
with an h1, but want to display it on a page that uses for example an h1
already as the website name (logo?).
You can use the package [hast-util-heading-rank][hast-util-heading-rank]
to get the rank of an element.
This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:
``sh`
npm install hast-util-shift-heading
In Deno with [esm.sh][esmsh]:
`js`
import {shiftHeading} from 'https://esm.sh/hast-util-shift-heading@4'
In browsers with [esm.sh][esmsh]:
`html`
`js
import {h} from 'hastscript'
import {shiftHeading} from 'hast-util-shift-heading'
const tree = h('main', [
h('h1', 'Alpha'),
h('p', 'Bravo'),
h('h2', 'Charlie'),
h('p', 'Delta'),
h('h5', 'Echo'),
h('p', 'Foxtrot'),
h('h6', 'Golf')
])
shiftHeading(tree, -1)
console.log(tree)
`
Yields:
`js`
{ type: 'element',
tagName: 'main',
properties: {},
children:
[ { type: 'element',
tagName: 'h1',
properties: {},
children: [Array] },
{ type: 'element',
tagName: 'p',
properties: {},
children: [Array] },
{ type: 'element',
tagName: 'h1',
properties: {},
children: [Array] },
{ type: 'element',
tagName: 'p',
properties: {},
children: [Array] },
{ type: 'element',
tagName: 'h4',
properties: {},
children: [Array] },
{ type: 'element',
tagName: 'p',
properties: {},
children: [Array] },
{ type: 'element',
tagName: 'h5',
properties: {},
children: [Array] } ] }
This package exports the identifier [shiftHeading][api-shift-heading].
There is no default export.
Change the rank of all headings (h1 to h6) in tree.
Mutates the tree.
Caps the rank so that shifting would not create invalid headings (so no h0 orh7).
###### Parameters
* tree ([Node][node]) — tree to changeshift
* (number) — non-null finite integer to use to shift ranks
###### Returns
Nothing (undefined).
###### Throws
When shift is not a valid non-null finite integer.
This package is fully typed with [TypeScript][].
It exports no additional types.
Projects maintained by the unified collective are compatible with maintained
versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
hast-util-shift-heading@^4, compatible with Node.js 16.
hast-util-shift-heading changes the syntax tree but can only generatedh1
headings from through h6.
There are no openings for [cross-site scripting (XSS)][xss] attacks.
* hast-util-heading
— check if a node is heading content
* hast-util-heading-rank
— get the rank (or depth, level) of headings
See [contributing.md][contributing] in [syntax-tree/.github][health] forsupport.md`][support] for ways to get help.
ways to get started.
See [
This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.
[MIT][license] © [Titus Wormer][author]
[build-badge]: https://github.com/syntax-tree/hast-util-shift-heading/workflows/main/badge.svg
[build]: https://github.com/syntax-tree/hast-util-shift-heading/actions
[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/hast-util-shift-heading.svg
[coverage]: https://codecov.io/github/syntax-tree/hast-util-shift-heading
[downloads-badge]: https://img.shields.io/npm/dm/hast-util-shift-heading.svg
[downloads]: https://www.npmjs.com/package/hast-util-shift-heading
[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=hast-util-shift-heading
[size]: https://bundlejs.com/?q=hast-util-shift-heading
[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
[backers-badge]: https://opencollective.com/unified/backers/badge.svg
[collective]: https://opencollective.com/unified
[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
[chat]: https://github.com/syntax-tree/unist/discussions
[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://wooorm.com
[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/main/support.md
[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
[hast]: https://github.com/syntax-tree/hast
[node]: https://github.com/syntax-tree/hast#nodes
[hast-util-heading-rank]: https://github.com/syntax-tree/hast-util-heading-rank
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[api-shift-heading]: #shiftheadingtree-shift