radiant-docs 0.1.6 → 0.1.8

package/template/src/lib/mdx/remark-code-block-component.ts

@@ -0,0 +1,342 @@
+import type { Root } from "mdast";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { mdxFromMarkdown } from "mdast-util-mdx";
+import { mdxjs } from "micromark-extension-mdxjs";
+import type { Plugin } from "unified";
+import { visitParents } from "unist-util-visit-parents";
+
+type CodeNode = {
+  type: "code";
+  lang?: string | null;
+  meta?: string | null;
+  value?: string | null;
+};
+
+type ParentNode = {
+  children?: unknown[];
+};
+
+type ParsedCodeMeta = {
+  filename: string;
+  showLineNumbers: boolean;
+  hideLanguageIcon: boolean;
+  highlightedLines: string;
+  collapsedLines: string;
+};
+
+type MdxJsxAttributeNode = {
+  type: "mdxJsxAttribute";
+  name: string;
+  value: string;
+};
+
+type MdxJsxFlowElementNode = {
+  type: "mdxJsxFlowElement";
+  name: string;
+  attributes: MdxJsxAttributeNode[];
+  children: unknown[];
+};
+
+type ParagraphNode = {
+  type: "paragraph";
+  children?: unknown[];
+};
+
+type MdxJsxTextElementNode = {
+  type: "mdxJsxTextElement";
+  name?: string | null;
+  attributes?: unknown[];
+  children?: unknown[];
+};
+
+const COMPONENT_PREVIEW_NAME = "ComponentPreview";
+const COMPONENT_PREVIEW_BLOCK_NAME = "ComponentPreviewBlock";
+const COMPONENT_PREVIEW_LANGUAGES = new Set(["jsx", "tsx", "mdx"]);
+const INTERNAL_CODE_BLOCK_NAME = "CodeBlockInternal";
+
+const FILE_EXTENSION_BY_LANGUAGE: Record<string, string> = {
+  bash: "sh",
+  shell: "sh",
+  c: "c",
+  cpp: "cpp",
+  csharp: "cs",
+  css: "css",
+  diff: "diff",
+  go: "go",
+  graphql: "graphql",
+  html: "html",
+  java: "java",
+  javascript: "js",
+  jsx: "jsx",
+  json: "json",
+  kotlin: "kt",
+  markdown: "md",
+  php: "php",
+  plaintext: "txt",
+  python: "py",
+  ruby: "rb",
+  rust: "rs",
+  sql: "sql",
+  swift: "swift",
+  toml: "toml",
+  typescript: "ts",
+  tsx: "tsx",
+  xml: "xml",
+  yaml: "yml",
+};
+
+function readMetaString(meta: string | null | undefined): string {
+  return typeof meta === "string" ? meta.trim() : "";
+}
+
+function parseMetaValue(meta: string, key: string): string {
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(
+    `(?:^|\\s)${escapedKey}=(?:\\{([^}]*)\\}|"([^"]*)"|'([^']*)'|\\\`([^\\\`]*)\\\`|([^\\s]+))`,
+  );
+  const match = meta.match(regex);
+  return (
+    match?.[1] ??
+    match?.[2] ??
+    match?.[3] ??
+    match?.[4] ??
+    match?.[5] ??
+    ""
+  ).trim();
+}
+
+function parseBooleanFlag(meta: string, key: string): boolean {
+  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const bareFlagRegex = new RegExp(`(?:^|\\s)${escapedKey}(?:\\s|$)`);
+  if (bareFlagRegex.test(meta)) return true;
+
+  const explicitTrueRegex = new RegExp(
+    `(?:^|\\s)${escapedKey}=\\{?["']?true["']?\\}?`,
+    "i",
+  );
+  return explicitTrueRegex.test(meta);
+}
+
+function parseHighlightedLines(meta: string): string {
+  const match = meta.match(/(?:^|\s)\{([^}]+)\}/);
+  return (match?.[1] ?? "").trim();
+}
+
+function parseParsedCodeMeta(meta: string): ParsedCodeMeta {
+  const filename = parseMetaValue(meta, "title");
+  const showLineNumbers = parseBooleanFlag(meta, "showLineNumbers");
+  const collapsedLines = parseMetaValue(meta, "collapse");
+  const highlightedLines = parseHighlightedLines(meta);
+  const hideLanguageIcon = parseBooleanFlag(meta, "hideLanguageIcon");
+
+  return {
+    filename,
+    showLineNumbers,
+    hideLanguageIcon,
+    highlightedLines,
+    collapsedLines,
+  };
+}
+
+function createAttribute(name: string, value: string): MdxJsxAttributeNode {
+  return {
+    type: "mdxJsxAttribute",
+    name,
+    value,
+  };
+}
+
+function parseComponentPreviewChildren(rawCode: string): unknown[] {
+  const parsedTree = fromMarkdown(rawCode, {
+    extensions: [mdxjs()],
+    mdastExtensions: [mdxFromMarkdown()],
+  }) as Root;
+
+  const children = Array.isArray(parsedTree.children) ? parsedTree.children : [];
+
+  // Promote a single inline MDX JSX node into flow-level JSX so the preview
+  // renders block components (e.g. <Callout />) as expected.
+  return children.map((node) => {
+    const paragraphNode = node as ParagraphNode;
+    if (
+      paragraphNode.type !== "paragraph" ||
+      !Array.isArray(paragraphNode.children) ||
+      paragraphNode.children.length !== 1
+    ) {
+      return node;
+    }
+
+    const onlyChild = paragraphNode.children[0] as MdxJsxTextElementNode;
+    if (
+      onlyChild.type !== "mdxJsxTextElement" ||
+      typeof onlyChild.name !== "string" ||
+      onlyChild.name.trim().length === 0
+    ) {
+      return node;
+    }
+
+    return {
+      type: "mdxJsxFlowElement",
+      name: onlyChild.name,
+      attributes: Array.isArray(onlyChild.attributes)
+        ? onlyChild.attributes
+        : [],
+      children: Array.isArray(onlyChild.children) ? onlyChild.children : [],
+    };
+  });
+}
+
+function getNearestMdxJsxFlowElementName(
+  ancestors: unknown[],
+): string | null {
+  for (let index = ancestors.length - 1; index >= 0; index -= 1) {
+    const ancestor = ancestors[index] as {
+      type?: string;
+      name?: string | null;
+    };
+    if (ancestor?.type !== "mdxJsxFlowElement") continue;
+    return typeof ancestor.name === "string" ? ancestor.name : null;
+  }
+
+  return null;
+}
+
+function isInsideMdxJsxTextElement(ancestors: unknown[]): boolean {
+  return ancestors.some((ancestor) => {
+    const node = ancestor as { type?: string };
+    return node?.type === "mdxJsxTextElement";
+  });
+}
+
+function buildDefaultCodeGroupFileName(
+  language: string,
+  codeIndexInGroup: number,
+): string {
+  const normalizedLanguage = language.trim().toLowerCase() || "plaintext";
+  const extension = FILE_EXTENSION_BY_LANGUAGE[normalizedLanguage] ?? "txt";
+  return `file-name-${codeIndexInGroup + 1}.${extension}`;
+}
+
+export const remarkCodeBlockComponent: Plugin<[], Root> = () => {
+  return (tree) => {
+    visitParents(tree, "code", (node, ancestors) => {
+      const codeNode = node as CodeNode;
+      const parent = ancestors[ancestors.length - 1] as ParentNode | undefined;
+      const siblings = parent?.children;
+      if (!siblings) return;
+
+      const currentIndex = siblings.indexOf(node);
+      if (currentIndex < 0) return;
+
+      const nearestMdxFlowElementName = getNearestMdxJsxFlowElementName(
+        ancestors,
+      );
+      const isInsideCodeGroup = nearestMdxFlowElementName === "CodeGroup";
+      const isInsideComponentPreview =
+        nearestMdxFlowElementName === COMPONENT_PREVIEW_NAME;
+      const isInsideInlineMdx = isInsideMdxJsxTextElement(ancestors);
+      if (isInsideInlineMdx) return;
+
+      const meta = readMetaString(codeNode.meta);
+      const parsedMeta = parseParsedCodeMeta(meta);
+      const language =
+        typeof codeNode.lang === "string" && codeNode.lang.trim().length > 0
+          ? codeNode.lang.trim()
+          : "plaintext";
+      const normalizedLanguage = language.trim().toLowerCase();
+      const rawCode = typeof codeNode.value === "string" ? codeNode.value : "";
+      const codeIndexInGroup = isInsideCodeGroup
+        ? siblings
+            .slice(0, currentIndex)
+            .filter(
+              (sibling) => (sibling as { type?: string }).type === "code",
+            ).length
+        : 0;
+      const fileName =
+        parsedMeta.filename.length > 0
+          ? parsedMeta.filename
+          : isInsideCodeGroup
+            ? buildDefaultCodeGroupFileName(language, codeIndexInGroup)
+            : "";
+      const showFilename = isInsideCodeGroup || fileName.length > 0;
+
+      const attributes: MdxJsxAttributeNode[] = [
+        createAttribute("language", language),
+        createAttribute("raw", rawCode),
+        createAttribute("showFilename", showFilename ? "true" : "false"),
+        createAttribute(
+          "showLineNumbers",
+          parsedMeta.showLineNumbers ? "true" : "false",
+        ),
+      ];
+
+      if (parsedMeta.hideLanguageIcon) {
+        attributes.push(createAttribute("hideLanguageIcon", "true"));
+      }
+
+      if (showFilename) {
+        attributes.push(createAttribute("filename", fileName));
+      }
+
+      if (isInsideCodeGroup) {
+        attributes.push(createAttribute("inCodeGroup", "true"));
+      }
+
+      if (parsedMeta.highlightedLines.length > 0) {
+        attributes.push(
+          createAttribute("highlightedLines", parsedMeta.highlightedLines),
+        );
+      }
+
+      if (parsedMeta.collapsedLines.length > 0) {
+        attributes.push(
+          createAttribute("collapsedLines", parsedMeta.collapsedLines),
+        );
+      }
+
+      if (isInsideComponentPreview) {
+        if (!COMPONENT_PREVIEW_LANGUAGES.has(normalizedLanguage)) {
+          throw new Error(
+            `[USER_ERROR]: <${COMPONENT_PREVIEW_NAME}>: Fenced code blocks must use jsx, tsx, or mdx language (received "${language}")`,
+          );
+        }
+
+        let previewChildren: unknown[] = [];
+        try {
+          previewChildren = parseComponentPreviewChildren(rawCode);
+        } catch (error) {
+          const reason =
+            error instanceof Error && error.message.trim().length > 0
+              ? ` -> ${error.message}`
+              : "";
+          throw new Error(
+            `[USER_ERROR]: <${COMPONENT_PREVIEW_NAME}>: Failed to parse fenced code block as MDX content${reason}`,
+          );
+        }
+
+        const previewAttributes = attributes.filter(
+          (attribute) => attribute.name !== "inCodeGroup",
+        );
+        const previewNode: MdxJsxFlowElementNode = {
+          type: "mdxJsxFlowElement",
+          name: COMPONENT_PREVIEW_BLOCK_NAME,
+          attributes: previewAttributes,
+          children: previewChildren,
+        };
+        siblings[currentIndex] = previewNode;
+        return;
+      }
+
+      const replacementNode: MdxJsxFlowElementNode = {
+        type: "mdxJsxFlowElement",
+        name: INTERNAL_CODE_BLOCK_NAME,
+        attributes,
+        children: [],
+      };
+
+      siblings[currentIndex] = replacementNode;
+    });
+  };
+};
+
+export default remarkCodeBlockComponent;

package/template/src/lib/mdx/remark-demote-h1.ts

@@ -0,0 +1,16 @@
+import type { Heading, Root } from "mdast";
+import type { Plugin } from "unified";
+import { visitParents } from "unist-util-visit-parents";
+
+export const remarkDemoteH1: Plugin<[], Root> = () => {
+  return (tree) => {
+    visitParents(tree, "heading", (node) => {
+      const heading = node as Heading;
+      if (heading.depth === 1) {
+        heading.depth = 2;
+      }
+    });
+  };
+};
+
+export default remarkDemoteH1;

package/template/src/lib/pagefind.ts

@@ -37,6 +37,7 @@ export interface PagefindSearchResponse {
 }
 
 export interface PagefindInstance {
+  options?: (options: { baseUrl?: string; basePath?: string }) => Promise<void>;
   init: () => Promise<void>;
   search: (
     query: string,
@@ -48,17 +49,30 @@ export interface PagefindInstance {
 
 let pagefindInstance: PagefindInstance | null = null;
 
+function getPagefindScriptUrl(): string {
+  return "/pagefind/pagefind.js";
+}
+
 export async function getPagefind(): Promise<PagefindInstance | null> {
   if (pagefindInstance) return pagefindInstance;
 
   try {
-    // Completely bypass Vite's module resolution by constructing the import dynamically
-    // This uses Function constructor to create a truly runtime import
+    // Completely bypass Vite's module resolution by constructing the import dynamically.
+    // This keeps Pagefind loading purely runtime and allows versioned query params.
     const importPagefind = new Function(
-      'return import("/pagefind/pagefind.js")'
-    ) as () => Promise<PagefindInstance>;
+      "moduleUrl",
+      "return import(moduleUrl)"
+    ) as (moduleUrl: string) => Promise<PagefindInstance>;
 
-    const pagefind = await importPagefind();
+    const pagefind = await importPagefind(getPagefindScriptUrl());
+    // Pagefind uses the script import location to derive result URL base.
+    // Since we import from the static host, force result links back to the
+    // current docs site origin while leaving asset fetches on static host.
+    if (typeof pagefind.options === "function") {
+      const baseUrl =
+        typeof window !== "undefined" ? window.location.origin : "/";
+      await pagefind.options({ baseUrl });
+    }
     await pagefind.init();
     pagefindInstance = pagefind;
     return pagefindInstance;

package/template/src/lib/routes.ts

@@ -37,10 +37,27 @@ export interface OpenApiRoute extends BaseRoute {
 // Discriminated union
 export type Route = MdxRoute | OpenApiRoute;
 
+function normalizeTitle(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length ? trimmed : undefined;
+}
+
+export function resolveMdxPageTitle(args: {
+  entry: any;
+  docsTitle?: unknown;
+  filePath: string;
+}): string {
+  const frontmatterTitle = normalizeTitle(args.entry?.data?.title);
+  const docsJsonTitle = normalizeTitle(args.docsTitle);
+
+  return frontmatterTitle || docsJsonTitle || deriveTitleFromEntryId(args.filePath);
+}
+
 function processPageItem(
   item: NavPageItem,
   parentSlug: string = "",
-  docs: any[]
+  docs: any[],
 ): MdxRoute {
   const filePath = typeof item === "string" ? item : item.page;
   const filename = filePath.split("/").pop() || filePath;
@@ -55,12 +72,17 @@ function processPageItem(
 
   if (!entry) {
     throw new Error(
-      `Could not find content collection entry for path: ${filePath}`
+      `Could not find content collection entry for path: ${filePath}`,
     );
   }
 
-  // Get title from frontmatter
-  const title = entry.data.title || deriveTitleFromEntryId(entry.filePath);
+  // Get title from docs.json NavPage object first, then fallback to filename
+  const configTitle = typeof item === "object" ? item.title : undefined;
+  const title = resolveMdxPageTitle({
+    entry,
+    docsTitle: configTitle,
+    filePath,
+  });
 
   return {
     type: "mdx",
@@ -73,7 +95,7 @@ function processPageItem(
 function processGroup(
   group: NavGroup,
   parentSlug: string = "",
-  docs: any[]
+  docs: any[],
 ): Route[] {
   let routes: Route[] = [];
   const groupSlug = slugify(group.group);
@@ -86,7 +108,7 @@ function processGroup(
     } else if ("group" in item) {
       // Nested group
       routes = routes.concat(
-        processGroup(item as NavGroup, currentPrefix, docs)
+        processGroup(item as NavGroup, currentPrefix, docs),
       );
     }
   });
@@ -96,7 +118,7 @@ function processGroup(
 
 // Helper function to parse endpoint string (same as in validation.ts)
 function parseEndpointString(
-  endpointStr: string
+  endpointStr: string,
 ): { method: string; path: string } | null {
   const trimmed = endpointStr.trim();
   const parts = trimmed.split(/\s+/);
@@ -124,7 +146,7 @@ function shouldIncludeEndpoint(
   method: string,
   pathStr: string,
   include?: string[],
-  exclude?: string[]
+  exclude?: string[],
 ): boolean {
   // Normalize for comparison
   const normalizedMethod = method.toUpperCase();
@@ -155,7 +177,7 @@ function shouldIncludeEndpoint(
 
 async function processOpenApiFile(
   openApiPathOrConfig: string | NavOpenApi,
-  parentSlug: string = ""
+  parentSlug: string = "",
 ): Promise<OpenApiRoute[]> {
   const routes: OpenApiRoute[] = [];
   const CWD = process.cwd();
@@ -243,7 +265,7 @@ async function processOpenApiFile(
 async function processMenuItem(
   menuItem: NavMenuItem,
   parentSlug: string = "",
-  docs: any[]
+  docs: any[],
 ): Promise<Route[]> {
   let routes: Route[] = [];
   const menuItemSlug = slugify(menuItem.label);
@@ -253,17 +275,16 @@ async function processMenuItem(
 
   const submenu = menuItem.submenu;
 
-  // Process pages if they exist
+  // Process pages if they exist (pages array can contain pages and groups)
   if (submenu.pages) {
-    submenu.pages.forEach((page) => {
-      routes.push(processPageItem(page, currentPrefix, docs));
-    });
-  }
-
-  // Process groups if they exist
-  if (submenu.groups) {
-    submenu.groups.forEach((group) => {
-      routes = routes.concat(processGroup(group, currentPrefix, docs));
+    submenu.pages.forEach((item) => {
+      if (typeof item === "string" || "page" in item) {
+        routes.push(processPageItem(item as NavPageItem, currentPrefix, docs));
+      } else if ("group" in item) {
+        routes = routes.concat(
+          processGroup(item as NavGroup, currentPrefix, docs),
+        );
+      }
     });
   }
 
@@ -271,7 +292,7 @@ async function processMenuItem(
   if (submenu.openapi) {
     const openApiRoutes = await processOpenApiFile(
       submenu.openapi,
-      currentPrefix
+      currentPrefix,
     );
     routes = routes.concat(openApiRoutes);
   }
@@ -289,19 +310,16 @@ export async function getAllRoutes(): Promise<Route[]> {
 
   let allRoutes: Route[] = [];
 
-  // 3. Identify the active navigation container (pages, groups, or menu)
+  // 3. Identify the active navigation container (pages or menu)
   // We use the XOR guarantee from validateNavigation (only one key exists)
   if (navigation.pages) {
-    // Case 1: Simple pages array at the top level
+    // Case 1: Pages array at the top level (can contain pages and groups)
     navigation.pages.forEach((item) => {
-      // items are guaranteed to be string | NavPage
-      allRoutes.push(processPageItem(item, "", docs));
-    });
-  } else if (navigation.groups) {
-    // Case 2: Groups array at the top level
-    navigation.groups.forEach((group) => {
-      // items are guaranteed to be NavGroup
-      allRoutes = allRoutes.concat(processGroup(group, "", docs));
+      if (typeof item === "string" || "page" in item) {
+        allRoutes.push(processPageItem(item as NavPageItem, "", docs));
+      } else if ("group" in item) {
+        allRoutes = allRoutes.concat(processGroup(item as NavGroup, "", docs));
+      }
     });
   } else if (navigation.menu) {
     // Case 3: Menu object at the top level

package/template/src/lib/utils.ts

@@ -57,3 +57,23 @@ export function deriveTitleFromEntryId(filePath: string): string {
       .trim() || "Untitled"
   );
 }
+
+export function buildMdxPageHref(args: {
+  filePath: string;
+  groupSlug?: string;
+  homePath?: string;
+}): string {
+  if (args.homePath && args.filePath === args.homePath) {
+    return "/";
+  }
+
+  const filename = path.basename(args.filePath);
+  const pageSlug = slugify(filename);
+  const normalizedGroupSlug = (args.groupSlug || "")
+    .replace(/^\/+/, "")
+    .replace(/\/+$/, "");
+
+  return normalizedGroupSlug
+    ? `/${normalizedGroupSlug}/${pageSlug}`
+    : `/${pageSlug}`;
+}