prefer-to-for-internal-link-components

Prefer to over href for internal @docusaurus/Link component destinations.

Targeted pattern scope

This rule focuses on JSX/TSX files that import the default export from @docusaurus/Link.

It targets component usages such as:

<Link href="/docs/intro">
<DocsLink href="/docs/rules/overview">

when the destination is a static internal absolute route.

What this rule reports

This rule reports @docusaurus/Link components that use href for internal site routes.

Why this rule exists

The Docusaurus client API explicitly recommends Link for internal navigation.

For internal site routes, to is the right prop because it keeps Docusaurus client-side routing, preloading, and base URL behavior aligned with the framework's intended navigation model.

❌ Incorrect

import Link from "@docusaurus/Link";

export default function HomePage() {
 return <Link href="/docs/intro">Docs</Link>;
}

✅ Correct

import Link from "@docusaurus/Link";

export default function HomePage() {
 return <Link to="/docs/intro">Docs</Link>;
}

Behavior and migration notes

This rule provides an autofix that renames the internal-navigation prop from href to the routing prop used by @docusaurus/Link.

The rule only acts when:

the component comes from @docusaurus/Link
the route is a static internal absolute path
there is not already a to prop on the same JSX element

Additional examples

❌ Incorrect — aliased import

import DocsLink from "@docusaurus/Link";

export default function Hero() {
 return <DocsLink href="/docs/rules/overview">Rules</DocsLink>;
}

✅ Correct — external Link usage is left alone

import Link from "@docusaurus/Link";

export default function GitHubLink() {
 return (
  <Link href="https://github.com/Nick2bad4u/eslint-plugin-docusaurus-2">
   GitHub
  </Link>
 );
}

ESLint flat config example

import docusaurus2 from "eslint-plugin-docusaurus-2";

export default [docusaurus2.configs.recommended];

When not to use it

Do not use this rule if your project intentionally treats href as an acceptable prop for internal @docusaurus/Link usage and you do not want linting to normalize that distinction.

Rule catalog ID: R015

Targeted pattern scope​

What this rule reports​

Why this rule exists​

❌ Incorrect​

✅ Correct​

Behavior and migration notes​

Additional examples​

❌ Incorrect — aliased import​

✅ Correct — external Link usage is left alone​

ESLint flat config example​

When not to use it​

Further reading​