@terra-symposium/docs 0.1.72 → 0.1.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terra-symposium/docs",
-  "version": "0.1.72",
+	"version": "0.1.73",
   "description": "Terra Docs workspace and Markdown site generator.",
   "repository": {
     "type": "git",
@@ -64,13 +64,13 @@
     "@changesets/cli": "^3.0.3",
     "@eslint/js": "10.0.1",
     "@playwright/test": "^1.64.1",
+    "@terra-symposium/standards-quality": "2.1.0",
     "@terra-symposium/standards-reporting": "0.6.2",
     "@types/katex": "^0.16.8",
     "@types/node": "^24.19.2",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
     "@types/sanitize-html": "^2.16.2",
-    "@terra-symposium/standards-quality": "2.1.0",
     "@vitejs/plugin-react": "6.1.2",
     "eslint": "10.13.0",
     "husky": "^9.1.7",
@@ -83,6 +83,7 @@
     "vite": "8.3.4"
   },
   "dependencies": {
+    "@astrojs/markdown-remark": "7.3.5",
     "@astrojs/mdx": "8.1.2",
     "@astrojs/react": "^7.1.0",
     "@carbon/icons-react": "11.90.0",
@@ -98,9 +99,9 @@
     "@portabletext/editor": "7.9.0",
     "@radix-ui/react-popover": "^1.1.15",
     "@radix-ui/react-select": "2.4.1",
+    "@terra-symposium/styling": "0.1.34",
     "@uiw/codemirror-theme-github": "^4.25.9",
     "@xyflow/react": "^12.3.6",
-    "@terra-symposium/styling": "0.1.34",
     "astro": "^7.4.2",
     "jszip": "^3.10.1",
     "katex": "^0.19.1",

package/site/astro.config.mjs

@@ -5,6 +5,8 @@ import { createRequire } from 'node:module';
 import { defineConfig } from 'astro/config';
 import mdx from '@astrojs/mdx';
 import react from '@astrojs/react';
+import { unified } from '@astrojs/markdown-remark';
+import { basePathRemarkPlugin } from './base-path-remark-plugin.mjs';
 import { docsContentPlugin } from './docs-content-plugin.mjs';
 
 const packageRoot = fileURLToPath(new URL('../', import.meta.url));
@@ -13,6 +15,7 @@ const projectRoot = process.env.TERRA_DOCS_ROOT ?? process.cwd();
 const publicDir = resolve(projectRoot, '.terra-docs/public');
 const outDir = resolve(projectRoot, process.env.TERRA_DOCS_OUT ?? 'docs-dist');
 const site = process.env.TERRA_DOCS_SITE;
+const base = process.env.TERRA_DOCS_BASE ?? '/';
 const projectManifest = (() => {
 	try {
 		return JSON.parse(readFileSync(resolve(projectRoot, 'package.json'), 'utf8'));
@@ -40,7 +43,7 @@ const packageDependencyResolver = {
 	name: 'terra-docs-package-dependencies',
 	enforce: 'pre',
 	resolveId(source) {
-		if (!/^(?:astro|@astrojs\/(?:mdx|react))(?:\/|$)/.test(source)) return null;
+		if (!/^(?:astro|@astrojs\/(?:markdown-remark|mdx|react))(?:\/|$)/.test(source)) return null;
 		try {
 			return requireFromPackage.resolve(source);
 		} catch {
@@ -55,12 +58,13 @@ export default defineConfig({
 	publicDir,
 	outDir,
 	...(site ? { site } : {}),
-	base: process.env.TERRA_DOCS_BASE ?? '/',
+	base,
 	devToolbar: { enabled: false },
 	build: { format: 'directory' },
 	integrations: [react(), mdx()],
+	markdown: { processor: unified({ remarkPlugins: [[basePathRemarkPlugin, { base }]] }) },
 	vite: {
-		plugins: [packageDependencyResolver, docsContentPlugin({ root: projectRoot, base: process.env.TERRA_DOCS_BASE ?? '/' })],
+		plugins: [packageDependencyResolver, docsContentPlugin({ root: projectRoot, base })],
 		resolve: { alias: packageExportAliases() },
 		server: { fs: { allow: [projectRoot, packageRoot] } },
 	},

package/site/base-path-remark-plugin.mjs

@@ -0,0 +1,31 @@
+function addBasePath(value, base) {
+	if (typeof value !== 'string' || !value.startsWith('/') || value.startsWith('//') || base === '/') return value;
+	const basePath = `/${base.replace(/^\/+|\/+$/g, '')}`;
+	if (value === basePath) return `${basePath}/`;
+	if (value.startsWith(`${basePath}/`)) return value;
+	return `${basePath}${value}`;
+}
+
+function addBaseToHtml(source, base) {
+	return source.replace(/\b(href|src)=(['"])(\/[^'"#?]*)([^'"]*)\2/gi, (_match, attribute, quote, pathname, suffix) =>
+		`${attribute}=${quote}${addBasePath(`${pathname}${suffix}`, base)}${quote}`,
+	);
+}
+
+export function basePathRemarkPlugin({ base }) {
+	return (tree) => {
+		const visit = (node) => {
+			if (['link', 'image', 'definition'].includes(node.type) && typeof node.url === 'string') {
+				node.url = addBasePath(node.url, base);
+			}
+			if (node.type === 'html' && typeof node.value === 'string') {
+				node.value = addBaseToHtml(node.value, base);
+			}
+			if (node.type === 'mdxJsxAttribute' && ['href', 'src'].includes(node.name) && typeof node.value === 'string') {
+				node.value = addBasePath(node.value, base);
+			}
+			for (const child of node.children ?? []) visit(child);
+		};
+		visit(tree);
+	};
+}

package/site/docs-content-plugin.mjs

@@ -11,7 +11,7 @@ function publicRoute(file, docsRoot, base) {
 
 function rewriteTarget(rawTarget, sourceFile, docsRoot, base) {
 	const target = rawTarget.trim();
-	if (!target || /^(?:[a-z][a-z\d+.-]*:|\/\/|\/|#)/i.test(target)) return rawTarget;
+	if (!target || /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i.test(target)) return rawTarget;
 	const match = /^(<[^>]+>|[^\s]+)([\s\S]*)$/.exec(target);
 	if (!match) return rawTarget;
 	const bracketed = match[1].startsWith('<') && match[1].endsWith('>');
@@ -19,6 +19,19 @@ function rewriteTarget(rawTarget, sourceFile, docsRoot, base) {
 	const suffix = match[2];
 	const [filePath, ...hashParts] = pathname.split('#');
 	const [cleanPath, ...queryParts] = filePath.split('?');
+	const fragment = hashParts.length ? `#${hashParts.join('#')}` : '';
+	const query = queryParts.length ? `?${queryParts.join('?')}` : '';
+	if (cleanPath.startsWith('/')) {
+		const basePath = base === '/' ? '' : `/${base.replace(/^\/+|\/+$/g, '')}`;
+		const rootBase = `${basePath}/`;
+		const routedPath = base === '/' || cleanPath.startsWith(rootBase)
+			? cleanPath
+			: cleanPath === basePath
+				? rootBase
+				: `${basePath}${cleanPath}`;
+		const rewritten = `${routedPath}${query}${fragment}`;
+		return `${bracketed ? `<${rewritten}>` : rewritten}${suffix}`;
+	}
 	let resolvedPath;
 	try {
 		resolvedPath = resolve(sourceFile, '..', decodeURIComponent(cleanPath));
@@ -28,8 +41,6 @@ function rewriteTarget(rawTarget, sourceFile, docsRoot, base) {
 	const relativePath = relative(docsRoot, resolvedPath);
 	if (relativePath.startsWith(`..${sep}`) || relativePath === '..' || !existsSync(resolvedPath)) return rawTarget;
 	const extension = extname(resolvedPath).toLowerCase();
-	const fragment = hashParts.length ? `#${hashParts.join('#')}` : '';
-	const query = queryParts.length ? `?${queryParts.join('?')}` : '';
 	const rewritten = markdownExtensions.has(extension)
 		? publicRoute(resolvedPath, docsRoot, base)
 		: `${base}_terra-docs/assets/${relativePath.split(sep).join('/')}`;