{"id":27821515,"url":"https://github.com/rehypejs/rehype-document","last_synced_at":"2025-05-01T17:03:45.314Z","repository":{"id":45563377,"uuid":"61490860","full_name":"rehypejs/rehype-document","owner":"rehypejs","description":"plugin to wrap a fragment in a document","archived":false,"fork":false,"pushed_at":"2023-11-25T12:38:51.000Z","size":155,"stargazers_count":31,"open_issues_count":0,"forks_count":5,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-04-26T05:23:24.624Z","etag":null,"topics":["document","html","rehype","rehype-plugin","wrap"],"latest_commit_sha":null,"homepage":"https://unifiedjs.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rehypejs.png","metadata":{"funding":{"github":"unifiedjs","open_collective":"unified"},"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-06-19T17:05:40.000Z","updated_at":"2024-06-18T15:28:47.254Z","dependencies_parsed_at":"2024-06-18T15:28:44.886Z","dependency_job_id":"6a78e63a-347a-407a-bd71-bda9088a2ea9","html_url":"https://github.com/rehypejs/rehype-document","commit_stats":{"total_commits":129,"total_committers":6,"mean_commits":21.5,"dds":0.06201550387596899,"last_synced_commit":"6cc848a1f85f69c43fa83e51bc73d66c350240c3"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rehypejs%2Frehype-document","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rehypejs%2Frehype-document/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rehypejs%2Frehype-document/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rehypejs%2Frehype-document/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rehypejs","download_url":"https://codeload.github.com/rehypejs/rehype-document/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251912749,"owners_count":21664087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["document","html","rehype","rehype-plugin","wrap"],"created_at":"2025-05-01T17:01:45.997Z","updated_at":"2025-05-01T17:03:45.198Z","avatar_url":"https://github.com/rehypejs.png","language":"JavaScript","funding_links":["https://github.com/sponsors/unifiedjs","https://opencollective.com/unified"],"categories":["Plugins"],"sub_categories":[],"readme":"# rehype-document\n\n[![Build][badge-build-image]][badge-build-url]\n[![Coverage][badge-coverage-image]][badge-coverage-url]\n[![Downloads][badge-downloads-image]][badge-downloads-url]\n[![Size][badge-size-image]][badge-size-url]\n\n**[rehype][github-rehype]** plugin to wrap a fragment in a document.\n\n## Contents\n\n* [What is this?](#what-is-this)\n* [When should I use this?](#when-should-i-use-this)\n* [Install](#install)\n* [Use](#use)\n* [API](#api)\n  * [`unified().use(rehypeDocument[, options])`](#unifieduserehypedocument-options)\n  * [`Options`](#options)\n* [Example](#example)\n  * [Example: language and direction](#example-language-and-direction)\n  * [Example: CSS](#example-css)\n  * [Example: JS](#example-js)\n  * [Example: metadata and links](#example-metadata-and-links)\n* [Compatibility](#compatibility)\n* [Security](#security)\n* [Related](#related)\n* [Contribute](#contribute)\n* [License](#license)\n\n## What is this?\n\nThis package is a [unified][github-unified] ([rehype][github-rehype])\nplugin to wrap a fragment in a document.\nIt’s especially useful when going from a markdown file that represents an\narticle and turning it into a complete HTML document.\n\n**unified** is a project that transforms content with abstract syntax trees\n(ASTs).\n**rehype** adds support for HTML to unified.\n**hast** is the HTML AST that rehype uses.\nThis is a rehype plugin that wraps a fragment in a document.\n\n## When should I use this?\n\nThis project is useful when you want to turn a fragment\n(specifically,\nsome nodes that can exist in a `\u003cbody\u003e` element)\ninto a whole document\n(a `\u003chtml\u003e`, `\u003chead\u003e`, and `\u003cbody\u003e`, where the latter will contain the\nfragment).\n\nThis plugin can make fragments valid whole documents.\nIt’s not a (social) metadata manager.\nThat’s done by [`rehype-meta`][github-rehype-meta].\nYou can use both together.\n\n## Install\n\nThis package is [ESM only][github-gist-esm].\nIn Node.js (version 16+),\ninstall with [npm][npmjs-install]:\n\n```sh\nnpm install rehype-document\n```\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```js\nimport rehypeDocument from 'https://esm.sh/rehype-document@7'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import rehypeDocument from 'https://esm.sh/rehype-document@7?bundle'\n\u003c/script\u003e\n```\n\n## Use\n\nSay we have the following file `example.md`:\n\n```markdown\n# Pluto\n\nPluto is a dwarf planet in the Kuiper belt.\n```\n\n…and a module `example.js` :\n\n```js\nimport rehypeDocument from 'rehype-document'\nimport rehypeStringify from 'rehype-stringify'\nimport remarkParse from 'remark-parse'\nimport remarkRehype from 'remark-rehype'\nimport {read} from 'to-vfile'\nimport {unified} from 'unified'\n\nconst file = await unified()\n  .use(remarkParse)\n  .use(remarkRehype)\n  .use(rehypeDocument, {title: 'Pluto'})\n  .use(rehypeStringify)\n  .process(await read('example.md'))\n\nconsole.log(String(file))\n```\n\n…then running `node example.js` yields:\n\n```html\n\u003c!doctype html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n\u003cmeta charset=\"utf-8\"\u003e\n\u003ctitle\u003ePluto\u003c/title\u003e\n\u003cmeta content=\"width=device-width, initial-scale=1\" name=\"viewport\"\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003ch1\u003ePluto\u003c/h1\u003e\n\u003cp\u003ePluto is a dwarf planet in the Kuiper belt.\u003c/p\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n## API\n\nThis package exports no identifiers.\nIt exports the [TypeScript][] type [`Options`][api-options].\nThe default export is [`rehypeDocument`][api-rehype-document].\n\n### `unified().use(rehypeDocument[, options])`\n\nWrap a fragment in a document.\n\n###### Parameters\n\n* `options` ([`Options`][api-options], optional)\n  — configuration\n\n###### Returns\n\nTransform ([`Transformer`][github-unified-transformer]).\n\n### `Options`\n\nConfiguration (TypeScript type).\n\n###### Fields\n\n* `css`\n  (`Array\u003cstring\u003e` or `string`, optional)\n  — URLs to stylesheets to use in `\u003clink\u003e`s\n* `dir`\n  (`'auto'`, `'ltr'`, or `'rtl'`, optional)\n  — direction of the document\n* `js`\n  (`Array\u003cstring\u003e` or `string`, optional)\n  — URLs to scripts to use as `src` on `\u003cscript\u003e`s\n* `language`\n  (`string`, default: `'en'`)\n  — language of document; should be a [BCP 47][ietf-bcp47] language tag\n* `link`\n  (`Array\u003cProperties\u003e` or `Properties`, optional)\n  — generate extra `\u003clink\u003e`s with these properties;\n  passed as `properties` to [`hastscript`][github-hastscript] with `'link'`\n* `meta`\n  (`Array\u003cProperties\u003e` or `Properties`, optional)\n  — generate extra `\u003cmeta\u003e`s with these properties;\n  passed as `properties` to [`hastscript`][github-hastscript] with `'meta'`\n* `responsive`\n  (`boolean`, default: `true`)\n  — generate a `meta[viewport]`\n* `script`\n  (`Array\u003cstring\u003e` or `string`, optional)\n  — JavaScript source code of `\u003cscript\u003e`s to add at end of `body`\n* `style`\n  (`Array\u003cstring\u003e` or `string`, optional)\n  — CSS source code of `\u003cstyle\u003e`s to add\n* `title`\n  (`string`, optional)\n  — text to use as title;\n  defaults to the file name (if any);\n  can bet set with `file.data.matter.title`\n  ([`vfile-matter`][github-vfile-matter])\n  and `file.data.meta.title`\n  ([`rehype-infer-title-meta`][github-rehype-infer-title-meta]),\n  which are preferred\n\n## Example\n\n### Example: language and direction\n\nThis example shows how to set a language:\n\n```js\nimport rehypeDocument from 'rehype-document'\nimport rehypeParse from 'rehype-parse'\nimport rehypeStringify from 'rehype-stringify'\nimport {unified} from 'unified'\n\nconst file = await unified()\n  .use(rehypeParse, {fragment: true})\n  .use(rehypeDocument, {title: 'פּלוטאָ', language: 'yi', dir: 'rtl'})\n  .use(rehypeStringify)\n  .process('\u003ch1\u003eהעלא, פּלוטאָ!\u003c/h1\u003e')\n\nconsole.log(String(file))\n```\n\nYields:\n\n```html\n\u003c!doctype html\u003e\n\u003chtml dir=\"rtl\" lang=\"yi\"\u003e\n\u003chead\u003e\n\u003cmeta charset=\"utf-8\"\u003e\n\u003ctitle\u003eפּלוטאָ\u003c/title\u003e\n\u003cmeta content=\"width=device-width, initial-scale=1\" name=\"viewport\"\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003ch1\u003eהעלא, פּלוטאָ!\u003c/h1\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n### Example: CSS\n\nThis example shows how to reference CSS files and include stylesheets:\n\n```js\nimport rehypeDocument from 'rehype-document'\nimport rehypeParse from 'rehype-parse'\nimport rehypeStringify from 'rehype-stringify'\nimport {unified} from 'unified'\n\nconst file = await unified()\n  .use(rehypeParse, {fragment: true})\n  .use(rehypeDocument, {\n    css: 'https://example.com/index.css',\n    style: 'body { color: red }'\n  })\n  .use(rehypeStringify)\n  .process('')\n\nconsole.log(String(file))\n```\n\nYields:\n\n```html\n\u003c!doctype html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n\u003cmeta charset=\"utf-8\"\u003e\n\u003cmeta content=\"width=device-width, initial-scale=1\" name=\"viewport\"\u003e\n\u003cstyle\u003ebody { color: red }\u003c/style\u003e\n\u003clink href=\"https://example.com/index.css\" rel=\"stylesheet\"\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n### Example: JS\n\nThis example shows how to reference JS files and include scripts:\n\n```js\nimport rehypeDocument from 'rehype-document'\nimport rehypeParse from 'rehype-parse'\nimport rehypeStringify from 'rehype-stringify'\nimport {unified} from 'unified'\n\nconst file = await unified()\n  .use(rehypeParse, {fragment: true})\n  .use(rehypeDocument, {\n    js: 'https://example.com/index.js',\n    script: 'console.log(1)'\n  })\n  .use(rehypeStringify)\n  .process('')\n\nconsole.log(String(file))\n```\n\nYields:\n\n```html\n\u003c!doctype html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n\u003cmeta charset=\"utf-8\"\u003e\n\u003cmeta content=\"width=device-width, initial-scale=1\" name=\"viewport\"\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003cscript\u003econsole.log(1)\u003c/script\u003e\n\u003cscript src=\"https://example.com/index.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n### Example: metadata and links\n\nThis example shows how to define metadata and include links (other than styles):\n\n```js\nimport rehypeDocument from 'rehype-document'\nimport rehypeParse from 'rehype-parse'\nimport rehypeStringify from 'rehype-stringify'\nimport {unified} from 'unified'\n\nconst file = await unified()\n  .use(rehypeParse, {fragment: true})\n  .use(rehypeDocument, {\n    link: [\n      {href: '/favicon.ico', rel: 'icon', sizes: 'any'},\n      {href: '/icon.svg', rel: 'icon', type: 'image/svg+xml'}\n    ],\n    meta: [{content: 'rehype-document', name: 'generator'}]\n  })\n  .use(rehypeStringify)\n  .process('')\n\nconsole.log(String(file))\n```\n\nYields:\n\n```html\n\u003c!doctype html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n\u003cmeta charset=\"utf-8\"\u003e\n\u003cmeta content=\"width=device-width, initial-scale=1\" name=\"viewport\"\u003e\n\u003cmeta content=\"rehype-document\" name=\"generator\"\u003e\n\u003clink href=\"/favicon.ico\" rel=\"icon\" sizes=\"any\"\u003e\n\u003clink href=\"/icon.svg\" rel=\"icon\" type=\"image/svg+xml\"\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n\u003e 💡 **Tip**:\n\u003e [`rehype-meta`][github-rehype-meta] is a (social) metadata manager.\n\n## Compatibility\n\nProjects maintained by the unified collective are compatible with maintained\nversions of Node.js.\n\nWhen we cut a new major release,\nwe drop support for unmaintained versions of Node.\nThis means we try to keep the current release line,\n`rehype-document@7`,\ncompatible with Node.js 16.\n\nThis plugin works with `rehype-parse` version 3+,\n`rehype-stringify` version 3+,\n`rehype` version 5+,\nand `unified` version 6+.\n\n## Security\n\nUse of `rehype-document` can open you up to a\n[cross-site scripting (XSS)][wikipedia-xss]\nattack if you pass user provided content in options.\nAlways be wary of user input and use\n[`rehype-sanitize`][github-rehype-sanitize].\n\n## Related\n\n* [`rehype-meta`][github-rehype-meta]\n  — add metadata to the head of a document\n* [`rehype-format`](https://github.com/rehypejs/rehype-format)\n  — format HTML\n* [`rehype-minify`](https://github.com/rehypejs/rehype-minify)\n  — minify HTML\n\n## Contribute\n\nSee [`contributing.md`][health-contributing] in [`rehypejs/.github`][health]\nfor ways to get started.\nSee [`support.md`][health-support] for ways to get help.\n\nThis project has a [code of conduct][health-coc].\nBy interacting with this repository,\norganization,\nor community you agree to abide by its terms.\n\n## License\n\n[MIT][file-license] © [Titus Wormer][wooorm]\n\n\u003c!-- Definitions --\u003e\n\n[api-options]: #options\n\n[api-rehype-document]: #unifieduserehypedocument-options\n\n[badge-build-image]: https://github.com/rehypejs/rehype-document/workflows/main/badge.svg\n\n[badge-build-url]: https://github.com/rehypejs/rehype-document/actions\n\n[badge-coverage-image]: https://img.shields.io/codecov/c/github/rehypejs/rehype-document.svg\n\n[badge-coverage-url]: https://codecov.io/github/rehypejs/rehype-document\n\n[badge-downloads-image]: https://img.shields.io/npm/dm/rehype-document.svg\n\n[badge-downloads-url]: https://www.npmjs.com/package/rehype-document\n\n[badge-size-image]: https://img.shields.io/bundlejs/size/rehype-document\n\n[badge-size-url]: https://bundlejs.com/?q=rehype-document\n\n[esmsh]: https://esm.sh\n\n[file-license]: license\n\n[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n\n[github-hastscript]: https://github.com/syntax-tree/hastscript\n\n[github-rehype]: https://github.com/rehypejs/rehype\n\n[github-rehype-infer-title-meta]: https://github.com/rehypejs/rehype-infer-title-meta\n\n[github-rehype-meta]: https://github.com/rehypejs/rehype-meta\n\n[github-rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize\n\n[github-unified]: https://github.com/unifiedjs/unified\n\n[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer\n\n[github-vfile-matter]: https://github.com/vfile/vfile-matter\n\n[health]: https://github.com/rehypejs/.github\n\n[health-coc]: https://github.com/rehypejs/.github/blob/HEAD/code-of-conduct.md\n\n[health-contributing]: https://github.com/rehypejs/.github/blob/HEAD/contributing.md\n\n[health-support]: https://github.com/rehypejs/.github/blob/HEAD/support.md\n\n[ietf-bcp47]: https://tools.ietf.org/html/bcp47\n\n[npmjs-install]: https://docs.npmjs.com/cli/install\n\n[typescript]: https://www.typescriptlang.org\n\n[wikipedia-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting\n\n[wooorm]: https://wooorm.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frehypejs%2Frehype-document","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frehypejs%2Frehype-document","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frehypejs%2Frehype-document/lists"}