rehype-document
Advanced tools
rehype plugin to wrap a fragment in a document.
This package is a unified (rehype) plugin to wrap a fragment in a document. It’s especially useful when going from a markdown file that represents an article and turning it into a complete HTML document.
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 wraps a fragment in a document.
This project is useful when you want to turn a fragment (specifically, some
nodes that can exist in a <body> element) into a whole document (a <html>,
<head>, and <body>, where the latter will contain the fragment).
This plugin can make fragments valid whole documents.
It’s not a (social) metadata manager.
That’s done by rehype-meta.
You can use both together.
This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:
npm install rehype-document
In Deno with Skypack:
import rehypeDocument from 'https://cdn.skypack.dev/rehype-document@6?dts'
In browsers with Skypack:
<script type="module">
import rehypeDocument from 'https://cdn.skypack.dev/rehype-document@6?min'
</script>
Say we have the following file example.md:
## Hello world!
This is **my** document.
And our module example.js looks as follows:
import {read} from 'to-vfile'
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeDocument from 'rehype-document'
import rehypeStringify from 'rehype-stringify'
main()
async function main() {
const file = await unified()
.use(remarkParse)
.use(remarkRehype)
.use(rehypeDocument, {title: 'Hi!'})
.use(rehypeStringify)
.process(await read('example.md'))
console.log(String(file))
}
Now running node example.js yields:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Hi!</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<h2>Hello world!</h2>
<p>This is <strong>my</strong> document.</p>
</body>
</html>
This package exports no identifiers.
The default export is rehypeDocument.
unified().use(rehypeDocument[, options])Wrap a fragment in a document.
optionsConfiguration (optional).
options.titleText to use as title (string, default: stem of file).
options.languageNatural language of document (string, default: 'en').
should be a BCP 47 language tag.
👉 Note: you should set this if the content isn’t in English.
options.responsiveWhether to insert a meta[viewport] (boolean, default: true).
options.styleCSS to include in head in <style> elements (string or Array<string>,
default: []).
options.cssLinks to stylesheets to include in head (string or Array<string>,
default: []).
options.metaMetadata to include in head (Object or Array<Object>, default: []).
Each object is passed as properties to hastscript with a
meta element.
options.linkLink tags to include in head (Object or Array<Object>, default: []).
Each object is passed as properties to hastscript with a
link element.
options.scriptInline scripts to include at end of body (string or Array<string>,
default: []).
options.jsExternal scripts to include at end of body (string or Array<string>,
default: []).
This example shows how to set a language:
import {unified} from 'unified'
import rehypeParse from 'rehype-parse'
import rehypeDocument from 'rehype-document'
import rehypeStringify from 'rehype-stringify'
main()
async function main() {
const file = await unified()
.use(rehypeParse, {fragment: true})
.use(rehypeDocument, {title: 'Плутон', language: 'ru'})
.use(rehypeStringify)
.process('<h1>Привет, Плутон!</h1>')
console.log(String(file))
}
Yields:
<!doctype html>
<html lang="ru">
<head>
<meta charset="utf-8">
<title>Плутон</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<h1>Привет, Плутон!</h1>
</body>
</html>
This example shows how to reference CSS files and include stylesheets:
import {unified} from 'unified'
import rehypeParse from 'rehype-parse'
import rehypeDocument from 'rehype-document'
import rehypeStringify from 'rehype-stringify'
main()
async function main() {
const file = await unified()
.use(rehypeParse, {fragment: true})
.use(rehypeDocument, {
css: 'https://example.com/index.css',
style: 'body { color: red }'
})
.use(rehypeStringify)
.process('')
console.log(String(file))
}
Yields:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>body { color: red }</style>
<link rel="stylesheet" href="https://example.com/index.css">
</head>
<body>
</body>
</html>
This example shows how to reference JS files and include scripts:
import {unified} from 'unified'
import rehypeParse from 'rehype-parse'
import rehypeDocument from 'rehype-document'
import rehypeStringify from 'rehype-stringify'
main()
async function main() {
const file = await unified()
.use(rehypeParse, {fragment: true})
.use(rehypeDocument, {
js: 'https://example.com/index.js',
script: 'console.log(1)'
})
.use(rehypeStringify)
.process('')
console.log(String(file))
}
Yields:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<script>console.log(1)</script>
<script src="https://example.com/index.js"></script>
</body>
</html>
This example shows how to define metadata and include links (other than styles):
import {unified} from 'unified'
import rehypeParse from 'rehype-parse'
import rehypeDocument from 'rehype-document'
import rehypeStringify from 'rehype-stringify'
main()
async function main() {
const file = await unified()
.use(rehypeParse, {fragment: true})
.use(rehypeDocument, {
link: [
{rel: 'icon', href: '/favicon.ico', sizes: 'any'},
{rel: 'icon', href: '/icon.svg', type: 'image/svg+xml'}
],
meta: [{name: 'generator', content: 'rehype-document'}]
})
.use(rehypeStringify)
.process('')
console.log(String(file))
}
Yields:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="generator" content="rehype-document">
<link rel="icon" href="/favicon.ico" sizes="any">
<link rel="icon" href="/icon.svg" type="image/svg+xml">
</head>
<body>
</body>
</html>
💡 Tip:
rehype-metais a (social) metadata manager.
This package is fully typed with TypeScript.
It exports an Options type, which specifies the interface of the accepted
options.
Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.
This plugin works with rehype-parse version 3+, rehype-stringify version 3+,
rehype version 5+, and unified version 6+.
Use of rehype-document can open you up to a cross-site scripting (XSS)
attack if you pass user provided content in options.
Always be wary of user input and use rehype-sanitize.
rehype-meta
— add metadata to the head of a documentrehype-format
— format HTMLrehype-minify
— minify HTMLSee contributing.md in rehypejs/.github for ways
to get started.
See support.md for ways to get help.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.
FAQs
rehype plugin to wrap a document around a fragment
We found that rehype-document demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Fluent Assertions is facing backlash after dropping the Apache license for a commercial model, leaving users blindsided and questioning contributor rights.
Research
Security News
Socket researchers uncover the risks of a malicious Python package targeting Discord developers.
Security News
The UK is proposing a bold ban on ransomware payments by public entities to disrupt cybercrime, protect critical services, and lead global cybersecurity efforts.