gnezim
182 lines
4.9 KiB
Markdown
182 lines
4.9 KiB
Markdown
# remark-external-links
|
||
|
||
[![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]
|
||
|
||
[**remark**][remark] plugin to automatically add `target` and `rel` attributes
|
||
to external links.
|
||
|
||
## Note!
|
||
|
||
This plugin is ready for the new parser in remark
|
||
([`remarkjs/remark#536`](https://github.com/remarkjs/remark/pull/536)).
|
||
The current and previous versions of the plugin work with the current and
|
||
previous versions of remark.
|
||
|
||
## Install
|
||
|
||
[npm][]:
|
||
|
||
```sh
|
||
npm install remark-external-links
|
||
```
|
||
|
||
## Use
|
||
|
||
Say we have the following file, `example.js`:
|
||
|
||
```js
|
||
var remark = require('remark')
|
||
var html = require('remark-html')
|
||
var externalLinks = require('remark-external-links')
|
||
|
||
remark()
|
||
.use(externalLinks, {target: false, rel: ['nofollow']})
|
||
.use(html)
|
||
.process('[remark](https://github.com/remarkjs/remark)', function(err, file) {
|
||
if (err) throw err
|
||
console.log(String(file))
|
||
})
|
||
```
|
||
|
||
Now, running `node example` yields:
|
||
|
||
```html
|
||
<p><a href="https://github.com/remarkjs/remark" rel="nofollow">remark</a></p>
|
||
```
|
||
|
||
## API
|
||
|
||
### `remark().use(externalLinks[, options])`
|
||
|
||
Automatically add `target` and `rel` attributes to external links.
|
||
|
||
##### `options`
|
||
|
||
###### `options.target`
|
||
|
||
How to display referenced documents (`string?`: `_self`, `_blank`, `_parent`,
|
||
or `_top`, default: `_blank`).
|
||
Pass `false` to not set `target`s on links.
|
||
|
||
###### `options.rel`
|
||
|
||
[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.
|
||
|
||
> 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']`).
|
||
|
||
###### `options.content`
|
||
|
||
[**hast**][hast] content to insert at the end of external links
|
||
([**Node**][node] or [**Children**][children]).
|
||
Will be inserted in a `<span>` element.
|
||
|
||
Useful for improving accessibility by [giving users advanced warning when
|
||
opening a new window][g201].
|
||
|
||
###### `options.contentProperties`
|
||
|
||
[`Properties`][properties] to add to the `span` wrapping `content`, when
|
||
given.
|
||
|
||
## Security
|
||
|
||
`options.content` is used and injected into the tree when it’s given.
|
||
This could open you up to a [cross-site scripting (XSS)][xss] attack if you pass
|
||
user provided content in.
|
||
|
||
This may become a problem if the Markdown later transformed to
|
||
[**rehype**][rehype] ([**hast**][hast]) or opened in an unsafe Markdown viewer.
|
||
|
||
Most likely though, this plugin will instead protect you from exploitation of
|
||
the `window.opener` API.
|
||
|
||
## Contribute
|
||
|
||
See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
|
||
to get started.
|
||
See [`support.md`][support] for ways to get help.
|
||
|
||
This project has a [code of conduct][coc].
|
||
By interacting with this repository, organization, or community you agree to
|
||
abide by its terms.
|
||
|
||
## License
|
||
|
||
[MIT][license] © [Cédric Delpoux][author]
|
||
|
||
<!-- Definitions -->
|
||
|
||
[build-badge]: https://img.shields.io/travis/remarkjs/remark-external-links/main.svg
|
||
|
||
[build]: https://travis-ci.org/remarkjs/remark-external-links
|
||
|
||
[coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark-external-links.svg
|
||
|
||
[coverage]: https://codecov.io/github/remarkjs/remark-external-links
|
||
|
||
[downloads-badge]: https://img.shields.io/npm/dm/remark-external-links.svg
|
||
|
||
[downloads]: https://www.npmjs.com/package/remark-external-links
|
||
|
||
[size-badge]: https://img.shields.io/bundlephobia/minzip/remark-external-links.svg
|
||
|
||
[size]: https://bundlephobia.com/result?p=remark-external-links
|
||
|
||
[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/remarkjs/remark/discussions
|
||
|
||
[npm]: https://docs.npmjs.com/cli/install
|
||
|
||
[health]: https://github.com/remarkjs/.github
|
||
|
||
[contributing]: https://github.com/remarkjs/.github/blob/HEAD/contributing.md
|
||
|
||
[support]: https://github.com/remarkjs/.github/blob/HEAD/support.md
|
||
|
||
[coc]: https://github.com/remarkjs/.github/blob/HEAD/code-of-conduct.md
|
||
|
||
[license]: license
|
||
|
||
[author]: https://xuopled.netlify.com
|
||
|
||
[remark]: https://github.com/remarkjs/remark
|
||
|
||
[mdn-rel]: https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types
|
||
|
||
[mdn-a]: https://developer.mozilla.org/en/docs/Web/HTML/Element/a
|
||
|
||
[hast]: https://github.com/syntax-tree/hast
|
||
|
||
[properties]: https://github.com/syntax-tree/hast#properties
|
||
|
||
[node]: https://github.com/syntax-tree/hast#nodes
|
||
|
||
[children]: https://github.com/syntax-tree/unist#child
|
||
|
||
[g201]: https://www.w3.org/WAI/WCAG21/Techniques/general/G201
|
||
|
||
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
|
||
|
||
[rehype]: https://github.com/rehypejs/rehype
|