Skip to main content

prefer-href-for-external-links

Prefer href over to for external Docusaurus config links.

Targeted pattern scopeโ€‹

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

It targets objects that look like navbar or footer link items and use:

  • to: "https://..."
  • to: "mailto:..."
  • to: "tel:..."

What this rule reportsโ€‹

This rule reports Docusaurus config link items that use to for external destinations.

Why this rule existsโ€‹

For Docusaurus theme config link objects, the docs distinguish between:

  • to for internal client-side navigation
  • href for external or full-page navigation

Using href for external destinations keeps the config aligned with the documented theme semantics and makes review intent clearer.

โŒ Incorrectโ€‹

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

โœ… Correctโ€‹

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

Behavior and migration notesโ€‹

This rule provides an autofix that replaces the external-destination key to with href for matching link items.

Additional examplesโ€‹

โŒ Incorrect โ€” external footer itemโ€‹

export default {
    themeConfig: {
        footer: {
            links: [
                {
                    title: "Project",
                    items: [
                        {
                            label: "NPM",
                            to: "https://www.npmjs.com/package/eslint-plugin-docusaurus-2",
                        },
                    ],
                },
            ],
        },
    },
};

โœ… Correct โ€” internal routes still use toโ€‹

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

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 standardizes on to for external Docusaurus config links and you do not want linting to enforce the theme docs distinction.

Rule catalog ID: R014

Further readingโ€‹