rehype-shift-heading
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizesize-badgesize
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechatrehype plugin to change the rank of headings.
Contents
* [`unified().use(rehypeShiftHeading[, options])`](#unifieduserehypeshiftheading-options)
* [`Options`](#options)
What is this?
This package is a unified (rehype) plugin to change the rank (also known as depth or level) of headings (so<h1>
through <h6>
).
You can increase (by passing a positive number) or decrease (negative number)
all headings.unified is a project that transforms content with abstract syntax trees (ASTs). rehype adds support for HTML to unified. hast is the HTML AST that rehype uses. This is a rehype plugin that changes headings in the tree.
When should I use this?
This plugin is particularly useful when merging documents into each other. For example, when injecting areadme.md
that starts with an <h1>
into a
site that uses an <h1>
for the title of the website.
This plugin can be used to shift all the headings inside the readme.This plugin is built on
hast-util-shift-heading
hast-util-shift-heading,
which does the work on syntax trees.
rehype focusses on making it easier to transform content by abstracting such
internals away.Install
This package is ESM onlyesm. In Node.js (version 16+), install with npm:npm install rehype-shift-heading
In Deno with
esm.sh
esmsh:import rehypeShiftHeading from 'https://esm.sh/rehype-shift-heading@2'
In browsers with
esm.sh
esmsh:<script type="module">
import rehypeShiftHeading from 'https://esm.sh/rehype-shift-heading@2?bundle'
</script>
Use
Say our moduleexample.js
looks as follows:import {rehype} from 'rehype'
import rehypeShiftHeading from 'rehype-shift-heading'
const file = await rehype()
.data('settings', {fragment: true})
.use(rehypeShiftHeading, {shift: 1})
.process('<h1>Alpha!</h1>')
console.log(String(file))
Now, running
node example
yields:<h2>Alpha!</h2>
API
This package exports no identifiers. The default export isrehypeShiftHeading
api-rehype-shift-heading.unified().use(rehypeShiftHeading[, options])
Change the rank (depth, level) of headings.Does not shift past
h1
and h6
.Parameters
options
(Options
api-options, optional)
— configuration
Returns
Transform (Transformer
unified-transformer).Options
Configuration (TypeScript type).Fields
shift
(number
, default:0
)
— number to shift headings; can be negative to decrease heading levels
Types
This package is fully typed with TypeScript. It exports the additional typeOptions
api-options.Compatibility
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,
rehype-shift-heading@^2
,
compatible with Node.js 16.This plugin works with
rehype-parse
version 1+, rehype-stringify
version 1+,
rehype
version 1+, and unified
version 4+.Security
Use ofrehype-shift-heading
is safe.Related
— add `id`s to headings
— add links to headings
Contribute
Seecontributing.md
contributing in rehypejs/.github
health for ways
to get started.
See support.md
support for ways to get help.This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.