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

.remarkrc.mjs

@@ -5,6 +5,7 @@ import remarkPresetLintRecommended from 'remark-preset-lint-recommended';
 import remarkNoInlineCodeFences from './src/plugins/remark-no-inline-code-fences.mjs';
 import remarkNoHtmlLinks from './src/plugins/remark-no-html-links.mjs';
 import remarkLintNoDeadUrls from 'remark-lint-no-dead-urls';
+import remarkForceRootRelative from './src/plugins/remark-force-root-relative.mjs';
 import remarkLintNoLiteralUrls from 'remark-lint-no-literal-urls';
 
 export default {
@@ -33,5 +34,6 @@ export default {
                   },
               ]
             : () => undefined,
+        remarkForceRootRelative,
     ],
 };

astro.config.mjs

@@ -10,6 +10,7 @@ import remarkImageAttributes from './src/plugins/remark-image-attributes';
 import { remarkMdxGlobalImports } from './src/plugins/remark-mdx-global-imports';
 import remarkCodeRegion from './src/plugins/remark-code-region';
 import { unified } from '@astrojs/markdown-remark';
+import rehypeTargetBlank from './src/plugins/rehype-external-links';
 
 export default defineConfig({
     site: 'https://frcsoftware.org',
@@ -25,6 +26,7 @@ export default defineConfig({
                 remarkMdxGlobalImports,
                 remarkCodeRegion,
             ],
+            rehypePlugins: [rehypeTargetBlank],
             remarkRehype: {
                 footnoteLabel: 'References',
                 footnoteLabelTagName: 'h4',

package.json

@@ -46,6 +46,7 @@
         "@astrojs/check": "^0.9.10",
         "@eslint/js": "^10.0.1",
         "@types/estree": "^1.0.9",
+        "@types/hast": "^3.0.5",
         "@types/mdast": "^4.0.4",
         "@types/node": "^26.4.0",
         "@frcsoftware/vale": "3.19.0",

src/plugins/rehype-external-links.ts

@@ -0,0 +1,33 @@
+import { visit } from 'unist-util-visit';
+import type { Root } from 'hast';
+export default function rehypeTargetBlank() {
+    return (tree: Root) => {
+        visit(tree, 'element', (node) => {
+            if (
+                node.tagName !== 'a' ||
+                typeof node.properties.href !== 'string' ||
+                !URL.canParse(node.properties.href) ||
+                // only match http/s
+                !/^https?:/.test(URL.parse(node.properties.href)!.protocol)
+            ) {
+                // only run on valid external links
+                return;
+            }
+            const target = node.properties.target;
+            node.properties.target = target ? target : '_blank';
+            let rel = node.properties.rel;
+            if (!rel) {
+                rel = ['noreferrer', 'noopener'];
+            } else {
+                // just in case someone overrides the remark rule
+                if (!(rel.includes('opener') || rel.includes('noopener'))) {
+                    rel.push('noopener');
+                }
+                if (!rel.includes('noreferrer')) {
+                    rel.push('noreferrer');
+                }
+            }
+            node.properties.rel = rel;
+        });
+    };
+}

src/plugins/remark-force-root-relative.mjs

@@ -0,0 +1,29 @@
+import { visit } from 'unist-util-visit';
+
+export default function remarkForceRootRelative() {
+    /**
+     * @param {import("mdast").Root} tree
+     * @param {import("vfile").VFile} file
+     */
+    return (tree, file) => {
+        visit(tree, ['link', 'image', 'definition'], (node) => {
+            if (
+                (node.type !== 'link' &&
+                    node.type !== 'image' &&
+                    node.type !== 'definition') ||
+                !URL.canParse(node.url)
+            ) {
+                return;
+            }
+            // can't use the site property from astro.config.mjs, see https://github.com/withastro/starlight/pull/3572
+            const hostname = 'frcsoftware.org';
+            const url = new URL(node.url);
+            if (url.hostname === hostname) {
+                file.message(
+                    'Use root-relative URL syntax for internal links.',
+                    node,
+                ).fatal = true;
+            }
+        });
+    };
+}