@lexibase/rdx-next 3.1.0 → 4.0.0

package/README.md

@@ -16,6 +16,10 @@ must still be trusted project-owned content, not untrusted uploads.
 It exposes the `rdx` command used by generated projects to create their
 internal `.rdx` application and run Next.js.
 
+Run `pnpm rdx check` to validate static documentation links, heading fragments
+and local files in public/ before deployment. It reports source locations and
+exits nonzero for problems, without preparing the runtime or rendering documents.
+
 Run `pnpm rdx add versioning` (or `npm exec -- rdx add versioning`) from a
 documentation project to install and activate the official optional plugin.
 The command detects the package manager, preserves config and plugin options,
@@ -89,7 +93,6 @@ export default defineConfig({
     authors: [{ name: 'My team', url: 'https://example.com' }],
     keywords: ['documentation', 'my-project'],
     icons: { icon: '/favicon.ico' },
-    robots: { index: true, follow: true },
     openGraph: {
       type: 'website',
       images: [{ url: '/og.png', width: 1200, height: 630, alt: 'My project' }],
@@ -111,7 +114,7 @@ production domain or force localhost. Image, favicon and manifest paths refer
 to files you create in `public/`. Nothing creates those assets automatically.
 
 Supported fields are `metadataBase` (an absolute http(s) string),
-`applicationName`, `authors`, `keywords`, `icons`, `manifest`, `robots`,
+`applicationName`, `authors`, `keywords`, `icons`, `manifest`,
 `openGraph` and `twitter`. TypeScript describes the supported nested options,
 and invalid fields fail during configuration validation. This is a portable
 subset, not an unrestricted pass-through of all Next.js metadata options.

package/bin/cli.mjs

@@ -50,7 +50,12 @@ export async function runRdxCli({ templateDir } = {}) {
 
   async function main() {
     if (!command || command === 'help' || command === '--help') {
-      console.log('Usage: rdx <dev|build|start|prepare|add|plugin-command>')
+      console.log(
+        'Usage: rdx <dev|build|start|prepare|check|add|plugin-command>'
+      )
+      console.log(
+        '  rdx check: validate documentation links, sections and local assets'
+      )
       console.log('  rdx add versioning [--package-manager npm|pnpm|yarn]')
       console.log(
         'Plugin commands are registered through plugins in rdx.config.ts.'
@@ -58,6 +63,19 @@ export async function runRdxCli({ templateDir } = {}) {
       return
     }
 
+    if (command === 'check') {
+      if (
+        commandArgs.length === 1 &&
+        ['--help', '-h'].includes(commandArgs[0])
+      ) {
+        console.log(
+          'Usage: rdx check\nValidate static MDX links, section anchors and local public/ files without building the site.'
+        )
+        return
+      }
+      if (commandArgs.length) throw new Error('Usage: rdx check')
+    }
+
     if (command === 'add') {
       const { addVersioning, parseAddArguments } =
         await import('./add-plugin.mjs')
@@ -96,6 +114,17 @@ export async function runRdxCli({ templateDir } = {}) {
       rootDir: projectRoot,
       command,
     })
+    if (command === 'check') {
+      const { checkDocumentation, formatDocumentationCheck } =
+        await import('@lexibase/rdx-core/check')
+      const report = checkDocumentation(project)
+      const output = formatDocumentationCheck(report)
+      if (report.diagnostics.length) {
+        console.error(output)
+        process.exitCode = 1
+      } else console.log(output)
+      return
+    }
     if (command === 'prepare') {
       await prepareRuntime()
       console.log('RDX runtime prepared in .rdx/')
@@ -107,7 +136,7 @@ export async function runRdxCli({ templateDir } = {}) {
       )
       if (!pluginCommand)
         throw new Error(
-          `Unknown command "${command}". Available: dev, build, start, prepare, add${project.commands.map((entry) => `, ${entry.name}`).join('')}. Install and configure the plugin that provides this command.`
+          `Unknown command "${command}". Available: dev, build, start, prepare, check, add${project.commands.map((entry) => `, ${entry.name}`).join('')}. Install and configure the plugin that provides this command.`
         )
       await pluginCommand.run({
         rootDir: projectRoot,

package/config.d.mts

@@ -1,8 +1,13 @@
 /** Common build root for the documentation project and its installed Next.js. */
 export function getRdxBuildRoot(rootDir: string): Promise<string>
 
-/** Explicit deployment files for a native Next.js application using RDX. */
+/** Explicit deployment files and historical route redirects for a native Next.js application. */
 export function getRdxTracingConfig(options: {
   rootDir: string
   appDir?: string
-}): Promise<{ outputFileTracingIncludes: Record<string, string[]> }>
+}): Promise<{
+  outputFileTracingIncludes: Record<string, string[]>
+  redirects?: () => Promise<
+    { source: string; destination: string; permanent: boolean }[]
+  >
+}>

package/config.mjs

@@ -62,7 +62,7 @@ function literalPattern(filename) {
     .replace(/([*?[\]{}()!+@])/g, '\\$1')
 }
 
-/** Next.js tracing for configured RDX content, independent of plugin names. */
+/** Next.js tracing and historical route redirects, independent of plugin names. */
 export async function getRdxTracingConfig({ rootDir, appDir = rootDir }) {
   rootDir = path.resolve(rootDir)
   appDir = path.resolve(appDir)
@@ -77,11 +77,17 @@ export async function getRdxTracingConfig({ rootDir, appDir = rootDir }) {
   const project = await createRdxProject(input, { rootDir })
   const files = (
     await Promise.all(
-      project.sources.map((source) =>
-        contentFiles(
-          resolveProjectPath(rootDir, source.docsDir, 'content source docsDir')
+      project.sources
+        .filter((source) => source.redirectTo === undefined)
+        .map((source) =>
+          contentFiles(
+            resolveProjectPath(
+              rootDir,
+              source.docsDir,
+              'content source docsDir'
+            )
+          )
         )
-      )
     )
   ).flat()
   for (const filename of project.runtimeFiles) {
@@ -94,7 +100,15 @@ export async function getRdxTracingConfig({ rootDir, appDir = rootDir }) {
       throw new Error(`Plugin runtimeFiles must name a file: ${filename}`)
     files.push(resolved)
   }
+  const redirects = project.sources
+    .filter((source) => source.redirectTo !== undefined)
+    .map((source) => ({
+      source: `/docs/${source.routePrefix}/:path*`,
+      destination: `/docs/${source.redirectTo}/:path*`,
+      permanent: true,
+    }))
   return {
+    ...(redirects.length ? { redirects: async () => redirects } : {}),
     outputFileTracingIncludes: {
       '/*': [
         ...new Set(

package/dist/runtime/index.d.ts

@@ -1,14 +1,26 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { RdxProject, RDXConfig, RdxDocPage } from '@lexibase/rdx-types';
+import { RdxProject, RDXConfig, RdxContentSource, RdxDocPage } from '@lexibase/rdx-types';
 export { createRdxProject, getProjectDocsPaths } from '@lexibase/rdx-core';
-import { Metadata } from 'next';
+import { MetadataRoute, Metadata } from 'next';
 
 declare function getSearchSources(project: RdxProject): {
     source: string;
 }[];
 declare function getSearchResponse(project: RdxProject, key: string): Response;
 
+/** Published editions replace live development content in search results. */
+declare function getSourceRobots(project: RdxProject, source: RdxContentSource): {
+    index: boolean;
+    follow: boolean;
+};
+/** Use the configured public URL only; development hosts are never inferred. */
+declare function getRdxRobots(config: RDXConfig): MetadataRoute.Robots;
+/** Share the indexing policy while allowing host applications to map their URLs. */
+declare function getRdxSitemap(project: RdxProject, { documentPath, }?: {
+    documentPath?: (source: RdxContentSource, page: RdxDocPage) => string;
+}): MetadataRoute.Sitemap;
+
 /** Read metadata from the same content source and index used by the page. */
 declare function getDocumentMetadata({ project, slug, }: {
     project: RdxProject;
@@ -35,4 +47,4 @@ declare function DocsPage({ slug, project, }: {
     project: RdxProject;
 }): Promise<react.JSX.Element>;
 
-export { DocsPage, HomePage, NotFoundPage, RdxLayout, getDocumentMetadata, getPageMetadata, getRdxMetadata, getSearchResponse, getSearchSources };
+export { DocsPage, HomePage, NotFoundPage, RdxLayout, getDocumentMetadata, getPageMetadata, getRdxMetadata, getRdxRobots, getRdxSitemap, getSearchResponse, getSearchSources, getSourceRobots };

package/dist/runtime/index.js

@@ -2,7 +2,7 @@
 import {
   getDocument as getDocument2,
   getDocsPaths,
-  getSourceOptions as getSourceOptions2,
+  getSourceOptions as getSourceOptions3,
   resolveDocsRoute as resolveDocsRoute2
 } from "@lexibase/rdx-core";
 import { Button } from "@lexibase/rdx-ui/components/button";
@@ -11,6 +11,7 @@ import { DocsToc } from "@lexibase/rdx-ui/components/docs-toc";
 import { DocsPageTransition } from "@lexibase/rdx-ui/components/docs-page-transition";
 import { DocsSearch } from "@lexibase/rdx-ui/components/docs-search";
 import { Home } from "@lexibase/rdx-ui/components/home";
+import { SkipLink } from "@lexibase/rdx-ui/components/skip-link";
 import { FooterCredit } from "@lexibase/rdx-ui/components/footer-credit";
 import { Logo } from "@lexibase/rdx-ui/components/logo";
 import { getMdxComponents } from "@lexibase/rdx-ui/components/mdx-components";
@@ -22,7 +23,7 @@ import {
   VersionDropdown
 } from "@lexibase/rdx-ui/components/version-dropdown";
 import { ThemeProvider } from "@lexibase/rdx-ui/providers/theme-provider";
-import { notFound as notFound2, redirect } from "next/navigation";
+import { notFound as notFound2, redirect, permanentRedirect } from "next/navigation";
 
 // src/runtime/mdx.ts
 import { compileMDX } from "next-mdx-remote/rsc";
@@ -59,14 +60,16 @@ import { createRdxProject, getProjectDocsPaths } from "@lexibase/rdx-core";
 import { getDocsIndex, getDocument, getSourceOptions } from "@lexibase/rdx-core";
 import { buildSearchIndex } from "@lexibase/rdx-core/search";
 function getSearchSources(project) {
-  return project.config.search ? project.sources.map((source) => ({ source: source.routePrefix || "_" })) : [];
+  return project.config.search ? project.sources.filter((source) => source.redirectTo === void 0).map((source) => ({ source: source.routePrefix || "_" })) : [];
 }
 function getSearchResponse(project, key) {
-  if (!project.config.search) return new Response(null, { status: 404 });
+  const headers = { "X-Robots-Tag": "noindex, follow" };
+  if (!project.config.search)
+    return new Response(null, { status: 404, headers });
   const source = project.sources.find(
-    (entry) => (entry.routePrefix || "_") === key
+    (entry) => entry.redirectTo === void 0 && (entry.routePrefix || "_") === key
   );
-  if (!source) return new Response(null, { status: 404 });
+  if (!source) return new Response(null, { status: 404, headers });
   const options = getSourceOptions(project, source);
   const documents = getDocsIndex(options).flatMap(
     (category) => category.pages.map((page) => ({
@@ -81,7 +84,47 @@ function getSearchResponse(project, key) {
       content: getDocument(page.slug, options)?.content ?? ""
     }))
   );
-  return Response.json(buildSearchIndex(documents));
+  return Response.json(buildSearchIndex(documents), { headers });
+}
+
+// src/runtime/indexing.ts
+import { getDocsIndex as getDocsIndex2, getSourceOptions as getSourceOptions2 } from "@lexibase/rdx-core";
+function getSourceRobots(project, source) {
+  const published = project.sources.some(
+    (entry) => entry.id !== "current" && entry.redirectTo === void 0 && entry.badge !== "Archived"
+  );
+  return {
+    index: source.redirectTo === void 0 && source.badge !== "Archived" && (source.id !== "current" || !published),
+    follow: true
+  };
+}
+function getRdxRobots(config) {
+  return {
+    // Do not disallow noindex pages: crawlers must read their HTML directive.
+    rules: { userAgent: "*", allow: "/" },
+    ...config.metadata.metadataBase ? { sitemap: new URL("/sitemap.xml", config.metadata.metadataBase).href } : {}
+  };
+}
+function getRdxSitemap(project, {
+  documentPath = (source, page) => [
+    "/docs",
+    source.routePrefix,
+    page.slug.split("/").map(encodeURIComponent).join("/")
+  ].filter(Boolean).join("/")
+} = {}) {
+  const base = project.config.metadata.metadataBase;
+  if (!base) return [];
+  const urls = /* @__PURE__ */ new Set();
+  if (project.config.homepage?.enabled) urls.add(new URL("/", base).href);
+  for (const source of project.sources) {
+    if (!getSourceRobots(project, source).index) continue;
+    for (const category of getDocsIndex2(getSourceOptions2(project, source))) {
+      for (const page of category.pages) {
+        urls.add(new URL(documentPath(source, page), base).href);
+      }
+    }
+  }
+  return [...urls].map((url) => ({ url }));
 }
 
 // src/runtime/metadata.ts
@@ -92,10 +135,15 @@ function getDocumentMetadata({
   slug
 }) {
   const route = resolveDocsRoute(project, slug);
-  if (!route.slug) return {};
+  if (route.source.redirectTo !== void 0)
+    return { robots: getSourceRobots(project, route.source) };
+  if (!route.slug) return { robots: { index: false, follow: true } };
   if (!route.document) notFound();
   const page = route.categories.flatMap((category) => category.pages).find((page2) => page2.slug === route.slug);
-  return getPageMetadata(project.config, page);
+  return {
+    ...getPageMetadata(project.config, page),
+    robots: getSourceRobots(project, route.source)
+  };
 }
 function getPageMetadata(config, page) {
   const title = page.title;
@@ -115,6 +163,7 @@ function getRdxMetadata(config) {
     title: { default: name, template: `%s | ${name}` },
     description: config.description,
     ...metadata,
+    robots: { index: true, follow: true },
     ...metadataBase ? { metadataBase: new URL(metadataBase) } : {},
     ...metadata.openGraph ? {
       openGraph: {
@@ -140,7 +189,6 @@ function RdxLayout({
   config,
   bodyClassName
 }) {
-  const messages = getMessages(config.lang);
   return /* @__PURE__ */ jsx("html", { suppressHydrationWarning: true, lang: config.lang ?? "en", children: /* @__PURE__ */ jsx("body", { className: bodyClassName, children: /* @__PURE__ */ jsx(
     ThemeProvider,
     {
@@ -149,7 +197,7 @@ function RdxLayout({
       attribute: "class",
       defaultTheme: config.theme?.defaultTheme ?? "system",
       children: /* @__PURE__ */ jsxs(LocaleProvider, { lang: config.lang, children: [
-        /* @__PURE__ */ jsx("a", { className: "rdx-skip-link", href: "#rdx-main", children: messages.skipContent }),
+        /* @__PURE__ */ jsx(SkipLink, { lang: config.lang }),
         /* @__PURE__ */ jsx("div", { className: "flex flex-col h-dvh", children })
       ] })
     }
@@ -162,8 +210,8 @@ function RdxHeader({
   const { config } = project;
   const messages = getMessages(config.lang);
   const { source, slug: currentSlug } = resolveDocsRoute2(project, slug);
-  const options = project.sources.map((edition) => {
-    const docs = getSourceOptions2(project, edition);
+  const options = project.sources.filter((edition) => edition.redirectTo === void 0).map((edition) => {
+    const docs = getSourceOptions3(project, edition);
     const destination = currentSlug && getDocument2(currentSlug, docs) ? currentSlug : getDocsPaths(docs)[0];
     return {
       id: edition.id,
@@ -239,6 +287,14 @@ async function DocsPage({
     document,
     categories
   } = resolveDocsRoute2(project, slug);
+  if (source.redirectTo !== void 0)
+    permanentRedirect(
+      [
+        "/docs",
+        source.redirectTo,
+        ...slug?.slice(1).map(encodeURIComponent) ?? []
+      ].join("/")
+    );
   if (!currentSlug)
     return /* @__PURE__ */ jsxs(Fragment, { children: [
       /* @__PURE__ */ jsx(RdxHeader, { project, slug }),
@@ -252,7 +308,7 @@ async function DocsPage({
     document.content,
     getMdxComponents(project.config.lang),
     {
-      sourceRoot: getSourceOptions2(project, source).docsDir,
+      sourceRoot: getSourceOptions3(project, source).docsDir,
       sourcePath: document.sourcePath,
       routePrefix: source.routePrefix,
       documents: categories.flatMap((category2) => category2.pages)
@@ -302,23 +358,23 @@ async function DocsPage({
                   {
                     className: `w-full min-h-full bg-background px-7 flex flex-col gap-5 pb-8 md:py-8 ${project.config.TOC ? "xl:pr-20" : ""}`,
                     children: [
-                      /* @__PURE__ */ jsxs("div", { className: "w-full flex flex-col gap-5 md:mx-auto md:max-w-[860px] pt-14 md:pt-0 flex-1", children: [
-                        /* @__PURE__ */ jsxs("header", { className: "mb-6", children: [
-                          source.badge && /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground mb-4", children: source.badge === "Archived" ? messages.archivedVersion : source.badge }),
-                          /* @__PURE__ */ jsx("span", { className: "text-xs text-zinc-600 font-semibold uppercase block -mb-0.5", children: category?.title }),
-                          /* @__PURE__ */ jsx("h1", { className: "text-4xl uppercase font-bold mb-2", children: title }),
-                          description && /* @__PURE__ */ jsx("p", { className: "text-sm text-ring max-w-[726px]", children: description })
-                        ] }),
-                        /* @__PURE__ */ jsx(
-                          "main",
-                          {
-                            id: "rdx-main",
-                            tabIndex: -1,
-                            className: "h-full w-full flex-1 max-w-[960px]",
-                            children: content
-                          }
-                        )
-                      ] }),
+                      /* @__PURE__ */ jsxs(
+                        "main",
+                        {
+                          id: "rdx-main",
+                          tabIndex: -1,
+                          className: "w-full flex flex-col gap-5 md:mx-auto md:max-w-[860px] pt-14 md:pt-0 flex-1 outline-none",
+                          children: [
+                            /* @__PURE__ */ jsxs("header", { className: "mb-6", children: [
+                              source.badge && /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground mb-4", children: source.badge === "Archived" ? messages.archivedVersion : source.badge }),
+                              /* @__PURE__ */ jsx("span", { className: "text-xs text-zinc-600 font-semibold uppercase block -mb-0.5", children: category?.title }),
+                              /* @__PURE__ */ jsx("h1", { className: "text-4xl uppercase font-bold mb-2", children: title }),
+                              description && /* @__PURE__ */ jsx("p", { className: "text-sm text-ring max-w-[726px]", children: description })
+                            ] }),
+                            /* @__PURE__ */ jsx("div", { className: "h-full w-full flex-1 max-w-[960px]", children: content })
+                          ]
+                        }
+                      ),
                       /* @__PURE__ */ jsxs("footer", { className: "flex flex-col", children: [
                         /* @__PURE__ */ jsxs("section", { className: "flex items-center justify-between", children: [
                           previous ? /* @__PURE__ */ jsx(
@@ -372,6 +428,9 @@ export {
   getPageMetadata,
   getProjectDocsPaths,
   getRdxMetadata,
+  getRdxRobots,
+  getRdxSitemap,
   getSearchResponse,
-  getSearchSources
+  getSearchSources,
+  getSourceRobots
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexibase/rdx-next",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "description": "The Next.js runtime for RDX documentation projects.",
   "license": "MIT",
   "type": "module",
@@ -51,11 +51,11 @@
     "next-mdx-remote": "^6.0.0",
     "remark-gfm": "^4",
     "typescript": "6.0.3",
-    "@lexibase/rdx-types": "1.1.1",
-    "@lexibase/rdx-core": "1.3.0"
+    "@lexibase/rdx-types": "2.0.0",
+    "@lexibase/rdx-core": "2.0.0"
   },
   "peerDependencies": {
-    "@lexibase/rdx-ui": "^3.1.0",
+    "@lexibase/rdx-ui": "^3.2.0",
     "next": "^16.4.2",
     "react": "^19.3.1",
     "react-dom": "^19.3.1"
@@ -81,7 +81,7 @@
     "react": "19.3.1",
     "react-dom": "19.3.1",
     "@rdx/eslint-config": "1.0.0",
-    "@lexibase/rdx-ui": "3.1.0",
+    "@lexibase/rdx-ui": "3.2.1",
     "@rdx/typescript-config": "1.0.0"
   },
   "scripts": {

package/src/runtime/styles.css

@@ -2,16 +2,4 @@
 /* Register the entry file directly: consumer ignore rules can hide nested dist folders. */
 @source '../../dist/runtime/index.js';
 
-/* Colors, buttons, dropdowns and typography come from the shared UI theme. */
-.rdx-skip-link {
-  position: fixed;
-  top: -100px;
-  left: 16px;
-  z-index: 100;
-  padding: 12px;
-  background: var(--background);
-  color: var(--foreground);
-}
-.rdx-skip-link:focus {
-  top: 12px;
-}
+/* Colors, focus navigation and typography come from the shared UI theme. */

package/templates/runtime/app/robots.ts

@@ -0,0 +1,6 @@
+import { getRdxRobots } from '@lexibase/rdx-next/runtime'
+import { getProject } from '../rdx-project'
+
+export default async function robots() {
+  return getRdxRobots((await getProject()).config)
+}

package/templates/runtime/app/sitemap.ts

@@ -0,0 +1,6 @@
+import { getRdxSitemap } from '@lexibase/rdx-next/runtime'
+import { getProject } from '../rdx-project'
+
+export default async function sitemap() {
+  return getRdxSitemap(await getProject())
+}