Plugins References

mark up text link out and refer @mdsvex/plugin-references@0.1.0-next.1

References

References, links for @user, #123, owner/repo#123 and commits, and for bare urls when asked

Install

pnpm add -D @mdsvex/plugin-references@next

Turn it on

import { references } from '@mdsvex/plugin-references';

mdsvex({ plugins: [references({ repo: 'sveltejs/svelte' })] });

What it reads

@user #123 owner/repo#45

reads text as it is written

An example

You write
Thanks @ada for #123, which also closes sveltejs/kit#45.

You get

Thanks @ada for #123, which also closes sveltejs/kit#45.

Build-time preview.

Turns the references people write in prose into links:

Thanks @ada for #123, which also closes sveltejs/kit#45. Landed in a1b2c3d.
<p>
	Thanks <a href="https://github.com/ada">@ada</a> for
	<a href="https://github.com/sveltejs/svelte/issues/123">#123</a>, which also
	closes <a href="https://github.com/sveltejs/kit/issues/45">sveltejs/kit#45</a>.
	Landed in
	<a href="https://github.com/sveltejs/svelte/commit/a1b2c3d"><code>a1b2c3d</code></a>.
</p>
writtenbecomes a link toneeds
@userthe user
owner/repo#123that issue or pull request
#123the issue or pull request in your reporepo
a commit hash of 7 to 40 charactersthe commit in your reporepo
https://example.com, www.example.comitselflinkify: true

A reference has to stand on its own, so an email address, a path such as /@ada, page#12 and a word like defaced are left alone, and so is one you escaped, \@ada. Nothing is touched in code, math, an attribute, an {expression}, or the text of a link you already wrote.

references({
	repo: string,
	mention: string | false | ((parts: { user }) => string | undefined),
	issue: string | false | ((parts: { repo, owner, name, number }) => string | undefined),
	commit: string | false | ((parts: { repo, owner, name, sha }) => string | undefined),
	linkify: boolean,
	attrs: Record<string, string> | ((kind) => Record<string, string> | undefined)
});
  • repo is the repository a bare #123 and a commit belong to, as owner/name. Without it neither is linked.
  • mention, issue and commit are the url of each kind. The defaults are GitHub's, such as https://github.com/{repo}/issues/{number}. A string takes placeholders, a function returns the url or nothing to leave the reference as text, and false turns the kind off. For another host:
references({
	repo: 'group/project',
	mention: 'https://gitlab.com/{user}',
	issue: 'https://gitlab.com/{repo}/-/issues/{number}',
	commit: 'https://gitlab.com/{repo}/-/commit/{sha}'
});
  • linkify also makes a link of a bare https://, http:// or www. url. The parser never does, on purpose: in mdsvex a url is a link when you mark it, <https://example.com>, and this option is where you opt in to the rest. Punctuation at the end of a url stays with the sentence, by the rules GitHub uses.
  • attrs are attributes for each link, or a function of the kind ('mention', 'issue', 'commit', 'url') that returns them.

It does not check that a user or an issue exists. With linkify, list it before the emoji plugin, so a shortcode inside a url is left alone. External links reads links while the document is parsed and does not see the ones made here, so give them rel through attrs.

compile() takes every plugin the same way, through its plugins option.

Options, from its types 6

repo?: string
The repository a bare `#123` and a commit belong to, as `owner/name`, without it only `@user` and `owner/name#123` are linked
mention?: Template<Mention>
The url of a user, `https://github.com/{user}` by default
issue?: Template<Issue>
The url of an issue or a pull request, `https://github.com/{repo}/issues/{number}` by default, it also takes `{owner}` and `{name}`
commit?: Template<Commit>
The url of a commit, `https://github.com/{repo}/commit/{sha}` by default
linkify?: boolean
`true` also makes a link of a bare `https://`, `http://` or `www.` url
attrs?: Record<string, string> | ((kind: ReferenceKind) => Record<string, string> | undefined)
Attributes for each link, such as a class, or a function that gives them for one kind of reference

mdsvex, markdown with Svelte in it. MIT licence.