Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rehypejs/rehype
HTML processor powered by plugins part of the @unifiedjs collective
https://github.com/rehypejs/rehype
ast html javascript rehype unified
Last synced: 5 days ago
JSON representation
HTML processor powered by plugins part of the @unifiedjs collective
- Host: GitHub
- URL: https://github.com/rehypejs/rehype
- Owner: rehypejs
- License: mit
- Created: 2016-02-25T09:11:41.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-10-15T11:46:36.000Z (19 days ago)
- Last Synced: 2024-10-18T17:09:44.400Z (16 days ago)
- Topics: ast, html, javascript, rehype, unified
- Language: JavaScript
- Homepage: https://unifiedjs.com
- Size: 600 KB
- Stars: 1,782
- Watchers: 12
- Forks: 89
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- License: license
Awesome Lists containing this project
- awesome - rehype - HTML processor powered by plugins part of the @unifiedjs collective (JavaScript)
- awesome-list - rehype
README
# [![rehype][logo]][unified]
[![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]
**rehype** is a tool that transforms HTML with plugins.
These plugins can inspect and change the HTML.
You can use rehype on the server, the client, CLIs, deno, etc.
## Intro
rehype is an ecosystem of plugins that work with HTML as structured data,
specifically ASTs (abstract syntax trees).
ASTs make it easy for programs to deal with HTML.
We call those programs plugins.
Plugins inspect and change trees.
You can use the many existing plugins or you can make your own.
* to learn HTML, see [MDN][] and [WHATWG HTML][html]
* for more about us, see [`unifiedjs.com`][site]
* for updates, see [Twitter][]
* for questions, see [support][]
* to help, see [contribute][] or [sponsor][] below
## Contents
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Plugins](#plugins)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [Sponsor](#sponsor)
* [License](#license)
## What is this?
With this project and a plugin, you can turn this HTML:
```html
Saturn
Saturn
Saturn is a gas giant composed predominantly of hydrogen and helium.
```
…into the following HTML:
```html
Saturn
Saturn
Saturn is a gas giant composed predominantly of hydrogen and helium.
```
Show example code
```js
import rehypeParse from 'rehype-parse'
import rehypePresetMinify from 'rehype-preset-minify'
import rehypeStringify from 'rehype-stringify'
import {unified} from 'unified'
const file = await unified()
.use(rehypeParse)
.use(rehypePresetMinify)
.use(rehypeStringify).process(`
Saturn
Saturn
Saturn is a gas giant composed predominantly of hydrogen and helium.
`)
console.log(String(file))
```
With another plugin, you can turn this HTML:
```html
Hi, Saturn!
```
…into the following HTML:
```html
Hi, Saturn!
```
Show example code
```js
/**
* @import {Root} from 'hast'
*/
import rehypeParse from 'rehype-parse'
import rehypeStringify from 'rehype-stringify'
import {unified} from 'unified'
import {visit} from 'unist-util-visit'
const file = await unified()
.use(rehypeParse, {fragment: true})
.use(myRehypePluginToIncreaseHeadings)
.use(rehypeStringify)
.process('
Hi, Saturn!
')
console.log(String(file))
function myRehypePluginToIncreaseHeadings() {
/**
* @param {Root} tree
*/
return function (tree) {
visit(tree, 'element', function (node) {
if (['h1', 'h2', 'h3', 'h4', 'h5'].includes(node.tagName)) {
node.tagName = 'h' + (Number(node.tagName.charAt(1)) + 1)
}
})
}
}
```
You can use rehype for many different things.
**[unified][]** is the core project that transforms content with ASTs.
**rehype** adds support for HTML to unified.
**[hast][]** is the HTML AST that rehype uses.
This GitHub repository is a monorepo that contains the following packages:
* [`rehype-parse`][rehype-parse]
— plugin to take HTML as input and turn it into a syntax tree (hast)
* [`rehype-stringify`][rehype-stringify]
— plugin to take a syntax tree (hast) and turn it into HTML as output
* [`rehype`][rehype-core]
— `unified`, `rehype-parse`, and `rehype-stringify`, useful when input and
output are HTML
* [`rehype-cli`][rehype-cli]
— CLI around `rehype` to inspect and format HTML in scripts
## When should I use this?
Depending on the input you have and output you want, you can use different parts
of rehype.
If the input is HTML, you can use `rehype-parse` with `unified`.
If the output is HTML, you can use `rehype-stringify` with `unified`
If both the input and output are HTML, you can use `rehype` on its own.
When you want to inspect and format HTML files in a project, you can use
`rehype-cli`.
## Plugins
rehype plugins deal with HTML.
You can choose from the many plugins that already exist.
Here are three good ways to find plugins:
* [`awesome-rehype`][awesome-rehype]
— selection of the most awesome projects
* [List of plugins][list-of-plugins]
— list of all plugins
* [`rehype-plugin` topic][topic]
— any tagged repo on GitHub
Some plugins are maintained by us here in the `@rehypejs` organization while
others are maintained by folks elsewhere.
Anyone can make rehype plugins, so as always when choosing whether to include
dependencies in your project, make sure to carefully assess the quality of
rehype plugins too.
## Types
The rehype organization and the unified collective as a whole is fully typed
with [TypeScript][].
Types for hast are available in [`@types/hast`][types-hast].
## 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 compatible with Node.js 16.
## Security
As improper use of HTML can open you up to a [cross-site scripting (XSS)][xss]
attacks, use of rehype can also be unsafe.
Use [`rehype-sanitize`][rehype-sanitize] to make the tree safe.
Use of rehype plugins could also open you up to other attacks.
Carefully assess each plugin and the risks involved in using them.
For info on how to submit a report, see our [security policy][security].
## Contribute
See [`contributing.md`][contributing] in [`rehypejs/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.
Join us in [Discussions][chat] to chat with the community and contributors.
This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.
## Sponsor
Support this effort and give back by sponsoring on [OpenCollective][collective]!
## License
[MIT][license] © [Titus Wormer][author]
[logo]: https://raw.githubusercontent.com/rehypejs/rehype/cb624bd/logo.svg?sanitize=true
[build-badge]: https://github.com/rehypejs/rehype/workflows/main/badge.svg
[build]: https://github.com/rehypejs/rehype/actions
[coverage-badge]: https://img.shields.io/codecov/c/github/rehypejs/rehype.svg
[coverage]: https://codecov.io/github/rehypejs/rehype
[downloads-badge]: https://img.shields.io/npm/dm/rehype.svg
[downloads]: https://www.npmjs.com/package/rehype
[size-badge]: https://img.shields.io/bundlejs/size/rehype
[size]: https://bundlejs.com/?q=rehype
[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/rehypejs/rehype/discussions
[health]: https://github.com/rehypejs/.github
[security]: https://github.com/rehypejs/.github/blob/main/security.md
[contributing]: https://github.com/rehypejs/.github/blob/main/contributing.md
[support]: https://github.com/rehypejs/.github/blob/main/support.md
[coc]: https://github.com/rehypejs/.github/blob/main/code-of-conduct.md
[license]: license
[author]: https://wooorm.com
[unified]: https://github.com/unifiedjs/unified
[types-hast]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/hast
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[typescript]: https://www.typescriptlang.org
[mdn]: https://developer.mozilla.org/docs/Web/HTML
[html]: https://html.spec.whatwg.org/multipage/
[twitter]: https://twitter.com/unifiedjs
[site]: https://unifiedjs.com
[topic]: https://github.com/topics/rehype-plugin
[hast]: https://github.com/syntax-tree/hast
[awesome-rehype]: https://github.com/rehypejs/awesome-rehype
[rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize
[rehype-parse]: packages/rehype-parse/
[rehype-stringify]: packages/rehype-stringify/
[rehype-core]: packages/rehype/
[rehype-cli]: packages/rehype-cli/
[list-of-plugins]: doc/plugins.md#list-of-plugins
[contribute]: #contribute
[sponsor]: #sponsor
