Skip to main content

prefer-to-for-internal-links

Prefer to over href for internal Docusaurus config links.

Targeted pattern scopeโ€‹

This rule focuses on Docusaurus config link-item objects in docusaurus.config.* files.

  • objects that look like navbar or footer link items
  • internal routes expressed with href: "/..."

External URLs such as GitHub or npm links are ignored.

What this rule reportsโ€‹

This rule reports Docusaurus config link items that use href for internal site routes.

  • href: "/docs/..." in navbar items
  • href: "/docs/..." in footer link items

Why this rule existsโ€‹

Docusaurus treats to and href differently.

  • to is for client-side internal navigation
  • href is for full-page navigation and external destinations
  • to also participates in Docusaurus base URL handling automatically

Using href for internal routes makes config less idiomatic and can weaken routing consistency.

โŒ Incorrectโ€‹

export default {
    themeConfig: {
        navbar: {
            items: [
                {
                    label: "Docs",
                    href: "/docs/intro",
                },
            ],
        },
    },
};

โœ… Correctโ€‹

export default {
    themeConfig: {
        navbar: {
            items: [
                {
                    label: "Docs",
                    to: "/docs/intro",
                },
            ],
        },
    },
};

Behavior and migration notesโ€‹

This rule provides an autofix that renames the property key from href to the client-routing to field for matching internal link items.

If a config object mixes other specialized Docusaurus link fields, review the result after autofix as part of normal config review.

Additional examplesโ€‹

โŒ Incorrect โ€” Footer itemโ€‹

export default {
    themeConfig: {
        footer: {
            links: [
                {
                    title: "Docs",
                    items: [
                        {
                            label: "Rules overview",
                            href: "/docs/rules/overview",
                        },
                    ],
                },
            ],
        },
    },
};

โœ… Correct โ€” External link stays hrefโ€‹

export default {
    themeConfig: {
        navbar: {
            items: [
                {
                    label: "GitHub",
                    href: "https://github.com/Nick2bad4u/eslint-plugin-docusaurus-2",
                },
            ],
        },
    },
};

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 those objects as generic data structures outside Docusaurus config semantics.

Rule catalog ID: R001

Further readingโ€‹