Plugins Link check

catch broken things @mdsvex/plugin-link-check@0.1.0-next.1

Link check

Link checking, warns about #anchors and links to other documents that go nowhere

Install

pnpm add -D @mdsvex/plugin-link-check@next

Turn it on

import { link_check } from '@mdsvex/plugin-link-check';

mdsvex({ heading_ids: true, plugins: [link_check()] });

It waits, as it reads the documents a page links to: the Vite plugin and compile_async compile such a document, compile throws a PluginAsyncError.

What it reads

[text](#id) [text](./page.svx#id)

acts on links · reads the whole document

An example

You write
# Install

See [the setup](#setup), [install](#install)
and [the guide](./guide.svx#usage).

and the file it reads, ./guide.svx
# Guide

## Use it
You get

The page is the same without the plugin. What it gives is its warnings:

  1. line 3 missing_anchor #setup links to no element of this document, none has the id "setup"
  2. line 4 missing_anchor ./guide.svx#usage links to /docs/guide.svx, which has no element with the id "usage"
Build-time preview.

Warns at every link that goes nowhere, with the line of the link, as the compile warns about anything else:

# Install

See [the setup](#setup), [the guide](../guide/+page.md#usage) and [the api](/api#options).
#setup links to no element of this document, none has the id "setup"
../guide/+page.md#usage links to src/routes/guide/+page.md, which has no element with the id "usage"
link_check({
	documents: boolean = true, // check links to other documents too
	heading_ids: boolean | { slug } = true, // how other documents' headings get ids
	routes: string, // the directory whose documents are routes, as links.routes
	extensions: string[] = ['.md', '.svx'],
	base: string, // a root url written with the base has it taken off
	ignore: (href, filename) => boolean,
	strict: boolean = false // fail the compile with a LinkCheckError
});
  • Within a page, #id is checked against every id the document gives an element: the ids of headings, which need heading_ids, an id typed on an element, the name of an <a>, the id arg of a directive, the fn- ids of footnotes and an id a plugin gave a node. #top and # need none. An id a component makes as it renders is not known, skip it with ignore.
  • Other documents are checked by file, ./guide.md#usage, relative to the document, and by route, /guide#usage, when routes names the directory of your routes, as links.routes does. A route is the document guide.md, guide/+page.md or guide/index.md, with each extension. A route with no such document is not reported, since it may be a Svelte page, and neither is a route inside a (group). A root url with no fragment is not checked.
  • What is read. Each linked document is read and compiled once for every document that links to it, with the heading_ids given to the plugin, so give it the value you give mdsvex when that is not true. A link to a document that does not exist is a warning too, and the file it names is watched, so creating it checks the link again.
  • In the dev server a document that links to another is a dependency of it. Change the headings of guide.md and every document that links to it compiles again and warns about what now goes nowhere.
  • strict fails a document that has a link that goes nowhere with a LinkCheckError, after the warnings, its links listing each one. Turn it on for a build:
export default defineConfig(({ command }) => ({
	plugins: [mdsvex({ plugins: [link_check({ strict: command === 'build' })] })]
}));

Other documents are read while the document compiles, so the Vite plugin and compile_async, with a read option, check them, and compile throws a PluginAsyncError for a document that links to another. documents: false checks links within a page alone, under compile too. Markdown links are checked, not an <a> typed as html, and not files that are no documents, such as images.

Options, from its types 7

documents?: boolean = true
Checks links to other documents and their ids, which reads them, so it takes compile_async with a read option or the vite plugin, false checks the links within a page alone and works under compile
heading_ids?: boolean | HeadingIdsOptions = true
How the headings of other documents get their ids, give it the heading_ids option of mdsvex when that is not true, the ids of the document being checked are the ones its compile made
routes?: string
The directory whose documents are routes, as links.routes of mdsvex, absolute or relative to the working directory, a root url such as /guide#install is then checked against the document of that route
extensions?: string[]
The extensions of documents, as links.extensions, .md and .svx when left out
base?: string
The base path, as a string links.base, a root url written with it has it taken off
ignore?: (href: string, filename: string | undefined) => boolean
True for a url that is not checked, such as an id a component makes
strict?: boolean
A document with a link that goes nowhere fails its compile with a LinkCheckError that lists each, after it warned about them, for a build that must not ship one

mdsvex, markdown with Svelte in it. MIT licence.