Plugins External links

link out and refer @mdsvex/plugin-external-links@0.1.0-next.1

External links

External link policy, rel and target on every link that leaves the site

Install

pnpm add -D @mdsvex/plugin-external-links@next

Turn it on

import { external_links } from '@mdsvex/plugin-external-links';

mdsvex({ plugins: [external_links({ target: '_blank', new_tab_label: 'opens in a new tab' })] });

What it reads

[text](https://…)

acts on links

An example

You write
Read [the spec](https://example.com/spec), then [the guide](/guide).

You get

Read the spec, then the guide.

Build-time preview.

Sets rel, and target when you ask for one, on every markdown link that leaves the site:

Read [the spec](https://example.com/spec), then [the guide](/guide).
<p>
	Read <a href="https://example.com/spec" rel="noopener noreferrer">the spec</a>,
	then <a href="/guide">the guide</a>.
</p>

A link is external when its url is absolute, with an http: or https: scheme, or protocol relative (//cdn.example.com/x), and its host is not one of internal_hosts. Autolinks count. Everything else is left as it was written: relative urls, #fragments, mailto: and other schemes, and a url whose host comes from an expression, such as {url} or {base}/docs, since the plugin can't know at build time where it goes. An expression after the host is fine: https://example.com/{slug} is external.

It sees markdown links only. An <a href> you typed as HTML is an element, not a link, and is rendered as you wrote it. A link a component renders is not seen either.

external_links({
	target: string,
	rel: string | string[] = ['noopener', 'noreferrer'],
	internal_hosts: string[],
	is_external: (href: string, external: boolean) => boolean,
	attrs: Record<string, string>,
	icon: boolean | Record<string, string>,
	new_tab_label: string
});
  • target is not set by default, so an external link opens where the reader chooses. target: '_blank' opens a new tab.
  • rel tokens are added to the ones a link already has. noreferrer keeps the address of your page out of the request to the other site. noopener is implied by it and by target="_blank" in current browsers, and is written out for older ones. nofollow is left out because it suits links your users wrote, not your own. rel: [] adds none.
  • internal_hosts are the hosts of your own site, such as ['example.com', 'www.example.com']. A host is compared whole, without its port.
  • is_external decides for each link in place of the built in test, whose answer is its second argument: (href, external) => external || href.endsWith('.pdf').
  • attrs are more attributes for an external link, such as a class.
  • icon appends an empty <span class="external-link-icon" aria-hidden="true"> to each external link for a stylesheet to draw. An object is the attributes of the span.
  • new_tab_label is what a screen reader says after a link that opens a new tab. It needs a target that opens one:
external_links({
	target: '_blank',
	icon: true,
	new_tab_label: 'opens in a new tab'
});
<a href="https://example.com/spec" rel="noopener noreferrer" target="_blank">
	the spec<span class="external-link-icon" role="img" aria-label="opens in a new tab"></span>
</a>

The label is the name of the span, read out as part of the link the way the alt of an icon would be. There is no default, since the plugin can't know the language of the page.

The plugin reads each link as it closes, so rel and target are there while a document is still streaming. It keeps a target the link already has and adds to its rel, so a plugin that sets either has to come before it in plugins. A replaced a gets rel and target as props.

Options, from its types 7

target?: string
The `target` of an external link, such as `'_blank'`, none by default
rel?: string | string[] = ['noopener', 'noreferrer']
`rel` tokens for an external link, added to the ones the link has
internal_hosts?: string[]
Hosts that are this site, a link to one is not external a host is compared whole and without its port, `example.com` does not cover `www.example.com`
is_external?: (href: string, external: boolean) => boolean
Decides whether a link is external, in place of the built in test, whose answer is the second argument
attrs?: Record<string, string>
More attributes for an external link, such as a class
icon?: boolean | Record<string, string>
An empty `<span>` at the end of each external link for a stylesheet to draw an icon in, `true` gives it `class="external-link-icon"`, an object is its attributes
new_tab_label?: string
What a screen reader says after a link that opens a new tab, such as `'opens in a new tab'`, it needs a `target` that opens one

mdsvex, markdown with Svelte in it. MIT licence.