diff --git a/.remarkrc.mjs b/.remarkrc.mjs new file mode 100644 index 0000000000..0da0b1e6a6 --- /dev/null +++ b/.remarkrc.mjs @@ -0,0 +1,73 @@ +/** + * Remark plugins that `npm run lint` runs on docs pages through the + * `mdx/remark` rule in `eslint.config.mjs`. + */ + +// Schemes such as https: and mailto:, in-page anchors, and protocol-relative URLs. +const NOT_A_PAGE_LINK = /^([a-z][a-z\d+.-]*:|#|\/\/)/i; + +const pathOf = (url) => url.split(/[?#]/)[0]; + +/** + * A Markdown link to a doc must be its relative file path with the extension, + * such as `./accordion.mdx`. Docusaurus resolves it to the page in the same + * version and fails the build if the file is missing, and editors can follow + * it. Without the extension it is a URL that Docusaurus cannot map to a file, + * and a leading `/` is read from the repo root by editors and GitHub. + * + * A JSX `href` never goes through that resolver, so it must be an absolute URL + * path without the extension, such as `/api/accordion`. A relative `href` + * resolves against the page's URL instead. + */ +const checkMarkdownLink = (url) => { + if (url === '' || NOT_A_PAGE_LINK.test(url)) return null; + const path = pathOf(url); + if (/\.mdx?$/.test(path)) { + return path.startsWith('/') + ? `Link to \`${url}\` by its relative file path, such as \`./accordion.mdx\`. Editors and GitHub read a leading \`/\` from the repo root.` + : null; + } + // Another extension is a static file, such as an image or a download. + if (/\.[a-z\d]+$/i.test(path)) return null; + return `\`${url}\` is a URL, not a file. Link to the doc's relative file path with its extension, such as \`./accordion.mdx\`, so the build checks the page exists in this version.`; +}; + +const checkJsxHref = (url) => { + if (url === '' || NOT_A_PAGE_LINK.test(url)) return null; + const path = pathOf(url); + if (/\.mdx?$/.test(path)) { + return `A JSX \`href\` is a URL, not a file. Drop the extension from \`${url}\`, such as \`/api/accordion\`.`; + } + if (!path.startsWith('/')) { + return `Make \`${url}\` an absolute URL path, such as \`/api/accordion\`, or \`/v8/api/accordion\` on a v8 page. A relative \`href\` resolves against the page's URL.`; + } + return null; +}; + +function docLinks() { + return (tree, file) => { + const report = (reason, node) => { + const message = file.message(reason, node); + message.source = 'ionic-docs'; + message.ruleId = 'doc-links'; + }; + const visit = (node) => { + if (node.type === 'link' || node.type === 'definition') { + const reason = checkMarkdownLink(node.url); + if (reason) report(reason, node); + } else if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') { + for (const attribute of node.attributes) { + if (attribute.name !== 'href' || typeof attribute.value !== 'string') continue; + const reason = checkJsxHref(attribute.value); + if (reason) report(reason, node); + } + } + node.children?.forEach(visit); + }; + visit(tree); + }; +} + +export default { + plugins: [docLinks], +}; diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d810e00760..d0ed437a46 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -227,7 +227,7 @@ Use Markdown for links and headings whenever possible. When you need JSX, such a - [``](https://docusaurus.io/docs/docusaurus-core#link) from `@docusaurus/Link` instead of ``. It handles the base URL and locale, and opens external URLs in a new tab with `rel="noopener noreferrer"`. - [``](https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin/prefer-docusaurus-heading) from `@theme/Heading` instead of `

` to `

`. -Link to another doc by its relative file path, with the extension, such as `[Accordion](./accordion.mdx)` or `[Config](../developing/config.mdx)`. Docusaurus resolves it to the page in the same version, the build fails if the file doesn't exist, and editors can follow it to the file. A JSX prop such as `href` skips that step, so use the URL path without `/docs` or an extension instead: `/api/accordion`, or `/v8/api/accordion` on a v8 page. +Link to another doc by its relative file path, with the extension, such as `[Accordion](./accordion.mdx)` or `[Config](../developing/config.mdx)`. Docusaurus resolves it to the page in the same version, the build fails if the file doesn't exist, and editors can follow it to the file. A JSX prop such as `href` skips that step, so use the URL path without `/docs` or an extension instead: `/api/accordion`, or `/v8/api/accordion` on a v8 page. `npm run lint` flags a link in either form that doesn't follow this. The build only checks links and anchors that go through Markdown or these components. A raw `` to a page that doesn't exist builds without errors, and a raw heading's `id` can't be used as a link target. diff --git a/eslint.config.mjs b/eslint.config.mjs index 6fbf665e7f..d94f6caae3 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -56,6 +56,12 @@ export default [ // Code samples are page content, not markup, so they are not linted. files: docsDirs.map((dir) => `${dir}/**/*.mdx`), plugins: { ...mdx.flat.plugins, '@docusaurus': docusaurus }, - rules: { ...mdx.flat.rules, ...rules }, + rules: { + ...mdx.flat.rules, + ...rules, + // Runs the remark plugins in .remarkrc.mjs. The preset only warns, which + // does not fail the lint. + 'mdx/remark': 'error', + }, }, ];