Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions .remarkrc.mjs
Original file line number Diff line number Diff line change
@@ -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],
};
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,7 +227,7 @@ Use Markdown for links and headings whenever possible. When you need JSX, such a
- [`<Link>`](https://docusaurus.io/docs/docusaurus-core#link) from `@docusaurus/Link` instead of `<a>`. It handles the base URL and locale, and opens external URLs in a new tab with `rel="noopener noreferrer"`.
- [`<Heading>`](https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin/prefer-docusaurus-heading) from `@theme/Heading` instead of `<h2>` to `<h6>`.

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 `<a href>` to a page that doesn't exist builds without errors, and a raw heading's `id` can't be used as a link target.

Expand Down
8 changes: 7 additions & 1 deletion eslint.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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',
},
},
];
Loading