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])
  • 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:

- 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:

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

unified().use(rehypeAbsorbSiblings[, options])

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

Parameters

• options (Options, optional)
  • configuration

Returns

Transform (Transformer)

Options

Configuration.

Fields

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

Examples

Example: using hr tags as section breaks

providing these options:

	unified()
		.use(remarkParse)
		.use(remarkRehype)
		.use(rehypeAbsorbSiblings, {
			alases: { hr: 'section' }
		})
		.use(rehypeStringify)

will transform this markdown:

This is section one

---

This is section two

into this html:

<section><p>This is section one</p></section>
<section><p>This is section two</p></section>

Example: footers with sections

providing these options:

	unified()
		.use(remarkRehype)
		.use(rehypeAbsorbSiblings, {
			greedy: { footer: true }
		})
		.use(rehypeStringify)

Will transform this html:

<p>This is a top-level section</p>
<footer></footer>
<p>This is the first footer section</p>
<hr>
<p>This is the second footer section</p>

into this:

<section><p>This is a top-level section</p></section>
<footer>
<section><p>This is the first footer section</p></section>
<hr>
<section><p>This is the second footer section</p></section>
</footer>

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

Compatibility

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.

Security

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

License

ACSL © Matthew Lyon