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'}`,
);