Enforce root-relative URL syntax and open links in new tabs

[httphypixelnet]

Description

Added

• rehype-external-links.ts: Rehype plugin to ensure external links open in a new tab
• remark-force-root-relative.mjs: Remark plugin to enforce root-relative URLs on internal links

Closes #37

Meta

Merge checklist:

• Pull Request title is short, imperative summary of proposed changes
• The description documents the what and why, including events that led to this PR
• Pull Request has been linted and formatted and follows the styleguide

[github-actions]

🌐 Preview URL: https://pr-142.frcsoftware.pages.dev

[samfreund]

I believe absolute links is covered by af64f50

I misinterpreted the purpose of the absolute links

[httphypixelnet]

I believe absolute links is covered by af64f50

The current lint/build tooling doesn't fail on src/content/docs/learning-course/stage1/stage1b/stage-overview.mdx so I'm going to assume it does not cover absolute links.

[samfreund]

I believe absolute links is covered by af64f50

The current lint/build tooling doesn't fail on src/content/docs/learning-course/stage1/stage1b/stage-overview.mdx so I'm going to assume it does not cover absolute links.

It does, I think the reason that doesn't work is because src/content/etc. is the root path. Haven't tested with that combination though, so can't confirm. Regardless, it doesn't cover some of the https links you're changing so that's a good fix.

[httphypixelnet]

Strange, you want me to investigate making the plugin work properly?

[samfreund]

root-relative plugin misses images and definitions. See MRE below.

import { VFile } from '/home/USER/frcsoftware.org/node_modules/vfile/index.js';
import remarkForceRootRelative from '/home/USER/frcsoftware.org/src/plugins/remark-force-root-relative.mjs';

const tree = {
    type: 'root',
    children: [
        {
            type: 'link',
            url: 'https://frcsoftware.org/docs/guide',
            children: [{ type: 'text', value: 'internal link' }],
        },
        {
            type: 'image',
            url: 'https://frcsoftware.org/images/logo.png',
            alt: 'logo',
        },
        {
            type: 'definition',
            label: 'logo-ref',
            identifier: 'logo-ref',
            url: 'https://frcsoftware.org/images/logo-2x.png',
        },
        {
            type: 'imageReference',
            identifier: 'logo-ref',
            label: 'logo-ref',
            referenceType: 'full',
            alt: 'logo 2x',
        },
    ],
};

const file = new VFile({ path: 'sample.mdx', value: 'sample' });
const transform = remarkForceRootRelative()(tree, file);

console.log('messages after running remark-force-root-relative:\n');
for (const msg of file.messages) {
    console.log(`  - ${msg.fatal ? 'FATAL' : 'warning'}: ${msg.reason}`);
}
if (file.messages.length === 0) {
    console.log('  (none)');
}

const flagged = (node) =>
    file.messages.some((m) => Array.isArray(m.ancestors) && m.ancestors.includes(node));

console.log('\nexpected: link should be flagged, image + definition should be flagged');
const link = tree.children[0];
const image = tree.children[1];
const definition = tree.children[2];
console.log(
    `  link       ${link.url.padEnd(45)} -> ${flagged(link) ? 'flagged' : 'NOT flagged'}`,
);
console.log(
    `  image      ${image.url.padEnd(45)} -> ${flagged(image) ? 'flagged' : 'NOT flagged'}`,
);
console.log(
    `  definition ${definition.url.padEnd(45)} -> ${flagged(definition) ? 'flagged' : 'NOT flagged'}`,
);

[samfreund]

the logic is more clear if we check inequality with an && operator

[samfreund]

Since we're returning for this as well, it can get lumped into the if statement above

[samfreund]

With the way we're currently doing it, any links that have target or rel properties get overriden. might be worth only writing them if there's not an extant property? I'm not sure what the best practice would be here, but this is something we should explore

[samfreund]

We shouldn't need /gm