Links and rewrite
links
Turns the links you write between documents into the urls your site serves, with no function to write. Both keys are off until you set them.
links: {
routes?: string;
base?: true | string | { import: string; from: string };
}On the atlas: link.
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' } });[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.svx | route |
|---|---|
./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.svx | left as written, nothing says which page it is |
../../lib/notes.svx | left as written, the file is outside routes |
./chart.png, ./data.json | left 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) 
<!-- 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: truedoes 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 thatimport_imagesimports.
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.
rewrite
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 + '/';
}
});[the repo](gh:pngwn/MDsveX) and [the guide](/guide)
<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 & 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
hreforsrcof an element typed as HTML. - Returning
''leaves the attribute out.
compile() takes the option too.