New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
rehype-external-links
Advanced tools
rehype-external-links - npm Package Compare versions
Comparing version 1.0.0 to 1.0.1
| /** | ||
| * Plugin to automatically add `target` and `rel` attributes to external links. | ||
| * | ||
| * @type {import('unified').Plugin<[Options?] | void[], Root>} | ||
| * @type {import('unified').Plugin<[Options?] | Array<void>, Root>} | ||
| */ | ||
@@ -44,6 +44,4 @@ export default function rehypeExternalLinks( | ||
| content?: | ||
| | import('hast').Element | ||
| | import('hast').Comment | ||
| | import('hast').Text | ||
| | (import('hast').Element | import('hast').Comment | import('hast').Text)[] | ||
| | import('hast').ElementContent | ||
| | import('hast').ElementContent[] | ||
| | undefined | ||
@@ -50,0 +48,0 @@ /** |
@@ -12,3 +12,3 @@ /** | ||
| * Pass `false` to not set `target`s on links. | ||
| * @property {string[]|string|false} [rel=['nofollow', 'noopener', 'noreferrer']] | ||
| * @property {Array<string>|string|false} [rel=['nofollow', 'noopener', 'noreferrer']] | ||
| * Link types to hint about the referenced documents. | ||
@@ -19,5 +19,5 @@ * Pass `false` to not set `rel`s on links. | ||
| * exploitation of the `window.opener` API. | ||
| * @property {string[]} [protocols=['http', 'https']] | ||
| * @property {Array<string>} [protocols=['http', 'https']] | ||
| * Protocols to check, such as `mailto` or `tel`. | ||
| * @property {ElementChild|ElementChild[]} [content] | ||
| * @property {ElementChild|Array<ElementChild>} [content] | ||
| * hast content to insert at the end of external links. | ||
@@ -44,3 +44,3 @@ * Will be inserted in a `<span>` element. | ||
| * | ||
| * @type {import('unified').Plugin<[Options?] | void[], Root>} | ||
| * @type {import('unified').Plugin<[Options?] | Array<void>, Root>} | ||
| */ | ||
@@ -47,0 +47,0 @@ export default function rehypeExternalLinks(options = {}) { |
| { | ||
| "name": "rehype-external-links", | ||
| "version": "1.0.0", | ||
| "version": "1.0.1", | ||
| "description": "rehype plugin to automatically add `target` and `rel` attributes to external links", | ||
@@ -55,3 +55,3 @@ "license": "MIT", | ||
| "typescript": "^4.0.0", | ||
| "xo": "^0.44.0" | ||
| "xo": "^0.47.0" | ||
| }, | ||
@@ -58,0 +58,0 @@ "scripts": { |
146
readme.md
@@ -11,12 +11,46 @@ # rehype-external-links | ||
| [**rehype**][rehype] plugin to automatically add `target` and `rel` attributes | ||
| to external links. | ||
| **[rehype][]** plugin to add `rel` (and `target`) to external links. | ||
| ## Contents | ||
| * [What is this?](#what-is-this) | ||
| * [When should I use this?](#when-should-i-use-this) | ||
| * [Install](#install) | ||
| * [Use](#use) | ||
| * [API](#api) | ||
| * [`unified().use(rehypeExternalLinks[, options])`](#unifieduserehypeexternallinks-options) | ||
| * [Types](#types) | ||
| * [Compatibility](#compatibility) | ||
| * [Security](#security) | ||
| * [Contribute](#contribute) | ||
| * [License](#license) | ||
| ## What is this? | ||
| This package is a [unified][] ([rehype][]) plugin to add `rel` (and `target`) | ||
| attributes to external links. | ||
| It is particularly useful when displaying user content on your reputable site, | ||
| because users could link to disreputable sources (spam, scams, etc), as search | ||
| engines and other bots will discredit your site for linking to them (or | ||
| legitimize their sites). | ||
| In short: linking to something signals trust, but you can’t trust users. | ||
| This plugin adds certain `rel` attributes to prevent that from happening. | ||
| **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 adds `rel` (and `target`) to `<a>`s in the AST. | ||
| ## When should I use this? | ||
| This project is useful when you want to display user content from authors you | ||
| don’t trust (such as comments), as they might include links you don’t endorse, | ||
| on your website. | ||
| ## Install | ||
| This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c): | ||
| Node 12+ is needed to use it and it must be `import`ed instead of `require`d. | ||
| This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). | ||
| In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: | ||
| [npm][]: | ||
| ```sh | ||
@@ -26,5 +60,19 @@ npm install rehype-external-links | ||
| In Deno with [Skypack][]: | ||
| ```js | ||
| import rehypeExternalLinks from 'https://cdn.skypack.dev/rehype-external-links@1?dts' | ||
| ``` | ||
| In browsers with [Skypack][]: | ||
| ```html | ||
| <script type="module"> | ||
| import rehypeExternalLinks from 'https://cdn.skypack.dev/rehype-external-links@1?min' | ||
| </script> | ||
| ``` | ||
| ## Use | ||
| Say we have the following module, `example.js`: | ||
| Say our module `example.js` looks as follows: | ||
@@ -38,16 +86,17 @@ ```js | ||
| const input = '[rehype](https://github.com/rehypejs/rehype)' | ||
| main() | ||
| unified() | ||
| .use(remarkParse) | ||
| .use(remarkRehype) | ||
| .use(rehypeExternalLinks, {target: false, rel: ['nofollow']}) | ||
| .use(rehypeStringify) | ||
| .process(input) | ||
| .then((file) => { | ||
| console.log(String(file)) | ||
| }) | ||
| async function main() { | ||
| const file = await unified() | ||
| .use(remarkParse) | ||
| .use(remarkRehype) | ||
| .use(rehypeExternalLinks, {target: false, rel: ['nofollow']}) | ||
| .use(rehypeStringify) | ||
| .process('[rehype](https://github.com/rehypejs/rehype)') | ||
| console.log(String(file)) | ||
| } | ||
| ``` | ||
| Now, running `node example` yields: | ||
| Now running `node example.js` yields: | ||
@@ -65,40 +114,63 @@ ```html | ||
| Automatically add `target` and `rel` attributes to external links. | ||
| Add `rel` (and `target`) to external links. | ||
| ##### `options` | ||
| Configuration (optional). | ||
| ###### `options.target` | ||
| How to display referenced documents (`string?`: `_self`, `_blank`, `_parent`, | ||
| How to open external documents (`string?`: `_self`, `_blank`, `_parent`, | ||
| or `_top`, default: `_blank`). | ||
| Pass `false` to not set `target`s on links. | ||
| > 👉 **Note**: [you should likely pass `false`][css-tricks]. | ||
| ###### `options.rel` | ||
| [Link types][mdn-rel] to hint about the referenced documents (`Array.<string>` | ||
| [Link types][mdn-rel] to hint about the referenced documents (`Array<string>` | ||
| or `string`, default: `['nofollow', 'noopener', 'noreferrer']`). | ||
| Pass `false` to not set `rel`s on links. | ||
| **Note**: when using a `target`, add [`noopener` and `noreferrer`][mdn-a] to | ||
| avoid exploitation of the `window.opener` API. | ||
| > 👉 **Note**: you should at least set `['nofollow']`. | ||
| > ⚠️ **Danger**: when using a `target`, add [`noopener` and `noreferrer`][mdn-a] | ||
| > to avoid exploitation of the `window.opener` API. | ||
| ###### `options.protocols` | ||
| Protocols to check, such as `mailto` or `tel` (`Array.<string>`, default: | ||
| `['http', 'https']`). | ||
| Protocols to see as external, such as `mailto` or `tel` (`Array<string>`, | ||
| default: `['http', 'https']`). | ||
| ###### `options.content` | ||
| [**hast**][hast] content to insert at the end of external links | ||
| ([**Node**][node] or [**Children**][children]). | ||
| **[hast][]** content to insert at the end of external links ([`Node`][node] or | ||
| [`Children`][children], optional). | ||
| Will be inserted in a `<span>` element. | ||
| Useful for improving accessibility by [giving users advanced warning when | ||
| opening a new window][g201]. | ||
| > 👉 **Note**: you should set this when using `target` to adhere to | ||
| > accessibility guidelines by [giving users advanced warning when opening a new | ||
| > window][g201]. | ||
| ###### `options.contentProperties` | ||
| [`Properties`][properties] to add to the `span` wrapping `content`, when | ||
| given. | ||
| Attributes to add to the `<span>`s wrapping `options.content` | ||
| ([`Properties`][properties], optional). | ||
| ## Types | ||
| This package is fully typed with [TypeScript][]. | ||
| It exports an `Options` type, which specifies the interface of the accepted | ||
| options. | ||
| ## Compatibility | ||
| 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 4+, and `unified` version 6+. | ||
| ## Security | ||
@@ -110,3 +182,3 @@ | ||
| Either do not combine this plugin with user content or use | ||
| [`rehype-sanitize`][sanitize]. | ||
| [`rehype-sanitize`][rehype-sanitize]. | ||
@@ -157,2 +229,4 @@ ## Contribute | ||
| [skypack]: https://www.skypack.dev | ||
| [health]: https://github.com/rehypejs/.github | ||
@@ -170,2 +244,6 @@ | ||
| [typescript]: https://www.typescriptlang.org | ||
| [unified]: https://github.com/unifiedjs/unified | ||
| [rehype]: https://github.com/rehypejs/rehype | ||
@@ -175,3 +253,3 @@ | ||
| [sanitize]: https://github.com/rehypejs/rehype-sanitize | ||
| [rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize | ||
@@ -191,1 +269,3 @@ [mdn-rel]: https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types | ||
| [g201]: https://www.w3.org/WAI/WCAG21/Techniques/general/G201 | ||
| [css-tricks]: https://css-tricks.com/use-target_blank/ |
No alert changes
Improved metrics
- Total package byte prevSize
15559
19.45%- Number of lines in readme file
263
43.72%Worsened metrics
- Lines of code
129
-1.53%No dependency changes