Reference Links and rewrite

Annotated source

routes is the directory whose files are served by their path, relative to the Vite root. A relative link to a document in it becomes that document's route, so a link works on GitHub and in an editor as well as on the site.

mdsvex({ links: { routes: 'src/routes' } });
src/routes/guide/+page.svx
[Install](../setup/+page.svx#install) and then read [the rest](./advanced/+page.svx).

<p><a href="/setup#install">Install</a> and then read <a href="/guide/advanced">the rest</a>.</p>

How a file becomes a route:

link, from src/routes/guide/+page.svxroute
./other.svx, other.svx/guide/other, the extension goes
../setup/+page.svx/setup, a last +page or index goes
../+page.svx, ../index.svx/
../(marketing)/pricing/+page.svx/pricing, a (group) goes
./other.svx?tab=a#x/guide/other?tab=a#x, the query and the fragment stay
../[slug]/+page.svxleft as written, nothing says which page it is
../../lib/notes.svxleft as written, the file is outside routes
./chart.png, ./data.jsonleft as written, only a file with one of your extensions is a document

base goes in front of every url that starts with one /, for links and for images, and after routes has made its routes. It takes one of three things:

// the base of your vite config
mdsvex({ links: { base: true } });
// a prefix of your own
mdsvex({ links: { base: '/docs' } });
// a function the page calls where it renders, such as resolve from SvelteKit
mdsvex({ links: { base: { import: 'resolve', from: '$app/paths' } } });
[Guide](/guide) ![Logo](/logo.png)

<!-- base: '/docs' -->
<p><a href="/docs/guide">Guide</a> <img src="/docs/logo.png" alt="Logo" /></p>

<!-- base: { import: 'resolve', from: '$app/paths' } -->
<script>
	import { resolve as __mdsvex_base } from '$app/paths';
</script>

<p><a href={__mdsvex_base('/guide')}>Guide</a> <img src={__mdsvex_base('/logo.png')} alt="Logo" /></p>

Use the function form in SvelteKit, where the base is only known when the page renders. Any module works: the export is called with the url and returns the url to use. import: 'default' names a default export. A document with no root url imports nothing.

  • base: true does nothing when Vite's base is relative or /.

Neither key touches a url with a scheme (https:, mailto:), a //host url, a #fragment or ?query alone, or a url with a Svelte expression such as /posts/{slug}.

  • Only markdown links and images are changed. An <a href> or <img src> you type as HTML stays as written, and so does an image that import_images imports.

compile() takes links too. There routes is compared with filename as written, so give both as absolute paths or both relative to one directory, extensions inside links says which files are documents (.md and .svx by default), and base: true is an error since there is no Vite config to read.

A function for whatever links does not cover. It is called for the url of every markdown link and of every markdown image that is not imported. A string replaces the url, and returning nothing keeps it.

rewrite: (
	url: string,
	ctx: { filename?: string; type: 'link' | 'image'; written: string }
) => string | null | undefined | void;
mdsvex({
	rewrite(url, { type }) {
		// [the repo](gh:pngwn/MDsveX)
		if (url.startsWith('gh:')) return 'https://github.com/' + url.slice(3);
		// a trailing slash on every internal link
		if (type === 'link' && /^\/(?!\/)[^?#]*[^/?#]$/.test(url)) return url + '/';
	}
});
You write
[the repo](gh:pngwn/MDsveX) and [the guide](/guide)

You get
Compiles to
<p>
  <a
    href="https://github.com/pngwn/MDsveX"
    >the repo</a
  >
  and <a href="/guide/">the guide</a>
</p>

ctx.filename is the document, ctx.type says whether the url is the href of a link or the src of an image, and ctx.written is the url as the document has it.

It runs after links.routes and before links.base. So url is already a route for a link to a document, and a root url you return still gets the base. It sees external urls and #fragment links too, since some sites rewrite those, so return nothing for a url you do not mean to change.

The url is the text of the document, with character references such as &amp; not decoded. What you return is written the same way, so returning url changes nothing. It is called once for each different url in a document, and it must be synchronous.

  • It never sees a url with a Svelte expression, an empty url, or the href or src of an element typed as HTML.
  • Returning '' leaves the attribute out.

compile() takes the option too.

mdsvex, markdown with Svelte in it. MIT licence.