rehype-absorb-siblings

rehype plugin that supports tree manipulation to group a document's tags to enforce a certain formation, such as header / section / footer.

Contents

- What is this?
- When should I use this?
- Future
- Install
- API
- [unified().use(rehypeAbsorbSiblings[, options])](#unifieduserehypeabsorbsiblings-options)
- Options
- Examples
- example: using hr tags as section breaks
- example: footers with sections
- Compatibility
- Security
- License

What is this?

This package is a unified(rehype) that looks at a node's children, and organizes such that child tags not specified will be included in the previous sibling on a specified list.

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 uses hast.

When should I use this?

This project is useful to enforce a header/section/footer structure on your document.

With the default options, a document with a tree such as:
``yaml
- header
- h1: This is a header
- hr
- p: This is section content
- hr
- p: This is another section's content
- footer
- p: This is footer content
`

will be reformed into:
`yaml
- header:
- h1: This is a header
- section:
- p: This is section content
- hr
- section:
- p: This is another section's content
- footer:
- p: This is footer content
`

This is designed to work with markdown editors which stick to the original markdwn rule of not parsing markdown syntax inside of html tags.

Future


This project is a work-in-progress, created around my own immediate use-case: forming a remark/rehype-processed markdown document into the desired shape. Rehype trees from remark-rehype are not full html documents, merely fragments. I plan to add support to specify which nodes to process, such as body.

Install

This package is ESM only. In Node.js (version 16+), install with npm:
`
npm install rehype-absorb-siblings
`

API

This package exports no identifiers. The default export is rehypeAbosrbSiblings.

$3

Rewrite the document's nodes according to options or the default options,

##### Parameters

* options (Options, optional)
- configuration

##### Returns

Transform (Transformer)

$3

Configuration.

##### Fields

- default: (string, default: section) -- the tag to use when there is not a current allowed tag
- allowed: (Array, default: ['header', 'section', 'hr', 'footer']) -- tags permitted at the root level of the node
- extraAllowed: (Array, optional) -- concatenated onto the allowed value, allows one to provide additional tags to the default ones.
- greedy: (Record, optional) -- keys are tag names which will absorb other non-greedy siblings. See example.
- stingy: (Array, default: ['hr']) -- tags that do not absorb their subsequent siblings
- aliases: (Record, optional) -- tag names that, when found, are converted another tag. See example.

$3

#### Example: using hr tags as section breaks

providing these options:
`javascript
unified()
.use(remarkParse)
.use(remarkRehype)
.use(rehypeAbsorbSiblings, {
alases: { hr: 'section' }
})
.use(rehypeStringify)
`

will transform this markdown:
`markdown
This is section one

---

This is section two
`

into this html:
`html


This is section one

This is section two

`

#### Example: footers with sections

providing these options:
`javascript
unified()
.use(remarkRehype)
.use(rehypeAbsorbSiblings, {
greedy: { footer: true }
})
.use(rehypeStringify)
`

Will transform this html:

`html


This is a top-level section

This is the first footer section

---

This is the second footer section

`

into this:

`html


This is a top-level section



`

The greedy option will continue to absorb subsequent siblings until another greedy sibling is found, in this case a second footer.

$3

This project is compatible with NodeJS version 20 and forward.

This plugin works with unified version 11+. It may work with versions 6+ but I have not tested it with those.

$3


Use of rehype-absorb-siblings` is safe by default.

$3

ACSL © Matthew Lyon