- Notifications
You must be signed in to change notification settings - Fork9
plugin to parse the tree again
License
rehypejs/rehype-raw
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
rehype plugin to parse the tree (and raw nodes) again, keepingpositional info okay.
This package is aunified (rehype) plugin to parse a document again.To understand how it works, requires knowledge of ASTs (specifically,hast).This plugin passes each node and embedded raw HTML through an HTML parser(parse5), to recreate a tree exactly as how a browser would parseit, while keeping the original data and positional info intact.
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 parses the tree again.
This plugin is particularly useful when coming from markdown and wanting tosupport HTML embedded inside that markdown (which requires passingallowDangerousHtml: true toremark-rehype).Markdown dictates how, say, a list item or emphasis can be parsed.We can use that to turn the markdown syntax tree into an HTML syntax tree.But markdown also dictates that things that look like HTML, are passed throughuntouched, even when it just looks like XML but doesn’t really make sense, so wecan’t normally use these strings of “HTML” to create an HTML syntax tree.This plugin can.It can be used to take those strings of HTML and include them into the syntaxtree as actual nodes.
If your final result is HTML and you trust content, then “strings” are fine(you can passallowDangerousHtml: true torehype-stringify, which passesHTML through untouched).But there are two main cases where a proper syntax tree is preferred:
- rehype plugins need a proper syntax tree as they operate on actual nodes toinspect or transform things, they can’t operate on strings of HTML
- other output formats (React, MDX, etc) need actual nodes and can’t handlestrings of HTML
This plugin is built onhast-util-raw, which does the work onsyntax trees.rehype focusses on making it easier to transform content by abstracting suchinternals away.
This package isESM only.In Node.js (version 16+), install withnpm:
npm install rehype-raw
In Deno withesm.sh:
importrehypeRawfrom'https://esm.sh/rehype-raw@7'
In browsers withesm.sh:
<scripttype="module">importrehypeRawfrom'https://esm.sh/rehype-raw@7?bundle'</script>
Say we have the following markdown fileexample.md:
<divclass="note">A mix of*markdown* and <em>HTML</em>.</div>
…and our moduleexample.js looks as follows:
importrehypeDocumentfrom'rehype-document'importrehypeFormatfrom'rehype-format'importrehypeRawfrom'rehype-raw'importrehypeStringifyfrom'rehype-stringify'importremarkParsefrom'remark-parse'importremarkRehypefrom'remark-rehype'import{read}from'to-vfile'import{unified}from'unified'constfile=awaitunified().use(remarkParse).use(remarkRehype,{allowDangerousHtml:true}).use(rehypeRaw).use(rehypeDocument,{title:'🙌'}).use(rehypeFormat).use(rehypeStringify).process(awaitread('example.md'))console.log(String(file))
…now runningnode example.js yields:
<!doctype html><htmllang="en"><head><metacharset="utf-8"><title>🙌</title><metaname="viewport"content="width=device-width, initial-scale=1"></head><body><divclass="note"><p>A mix of<em>markdown</em> and<em>HTML</em>.</p></div></body></html>
This package exports no identifiers.The default export isrehypeRaw.
Parse the tree (and raw nodes) again, keeping positional info okay.
options(Options, optional)— configuration
Transform (Transformer).
Configuration (TypeScript type).
passThrough(Array<string>, default:[])— list of custom hast node types to pass through (as in, keep); this optionis a bit advanced as it requires knowledge of ASTs, so we defer to the docsinhast-util-rawtagfilter?(boolean | null | undefined)— whether to disallow irregular tags inrawnodes according to GFMtagfilter (default:false);this affects the following tags,grouped by their kind:RAWTEXT(iframe,noembed,noframes,style,xmp),RCDATA(textarea,title),SCRIPT_DATA(script),PLAINTEXT(plaintext);when you know that you do not want authors to write these tags,you can enable this option to prevent their use from running amok.
This package is fully typed withTypeScript.It exports the additional typeOptions.
TheRaw node type is registered by and exposed fromremark-rehype.
Projects maintained by the unified collective are compatible with maintainedversions of Node.js.
When we cut a new major release, we drop support for unmaintained versions ofNode.This means we try to keep the current release line,rehype-raw@^7, compatiblewith Node.js 16.
TheallowDangerousHtml option inremark-rehype isdangerous, so see that plugin on how to make it safe.Otherwise, this plugin is safe.
Seecontributing.md inrehypejs/.github for waysto get started.Seesupport.md for ways to get help.
This project has acode of conduct.By interacting with this repository, organization, or community you agree toabide by its terms.
About
plugin to parse the tree again
