radiant-docs 0.1.22 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "radiant-docs",
-  "version": "0.1.22",
+  "version": "0.1.25",
   "description": "CLI tool for previewing Radiant documentation locally",
   "type": "module",
   "bin": {

package/template/astro.config.mjs

@@ -9,6 +9,8 @@ import path from "path";
 import { getConfig, validateMdxContent } from "./src/lib/validation";
 import remarkCodeBlockComponent from "./src/lib/mdx/remark-code-block-component";
 import remarkDemoteH1 from "./src/lib/mdx/remark-demote-h1";
+import remarkStandaloneImageComponent from "./src/lib/mdx/remark-standalone-image-component";
+import rehypeExternalLinks from "./src/lib/mdx/rehype-external-links";
 import remarkGfm from "remark-gfm";
 import rehypeSlug from "rehype-slug";
 import rehypeAutolinkHeadings from "rehype-autolink-headings";
@@ -270,9 +272,15 @@ export default defineConfig({
   },
   integrations: [
     mdx({
-      remarkPlugins: [remarkGfm, remarkDemoteH1, remarkCodeBlockComponent],
+      remarkPlugins: [
+        remarkGfm,
+        remarkDemoteH1,
+        remarkStandaloneImageComponent,
+        remarkCodeBlockComponent,
+      ],
       rehypePlugins: [
         rehypeSlug,
+        rehypeExternalLinks,
         [
           rehypeAutolinkHeadings,
           {

package/template/src/components/user/Image.astro

@@ -1,6 +1,7 @@
 ---
 import type { HTMLAttributes } from "astro/types";
 import { validateProps } from "../../lib/component-error";
+import { renderMarkdown } from "../../lib/utils";
 
 interface Props extends HTMLAttributes<"img"> {
   src: string;
@@ -8,6 +9,11 @@ interface Props extends HTMLAttributes<"img"> {
 
 const { title, ...attrs } = Astro.props;
 
+const captionHtml =
+  typeof title === "string" && title.trim().length > 0
+    ? (await renderMarkdown(title)).replace(/^<p>([\s\S]*)<\/p>\n?$/, "$1")
+    : "";
+
 validateProps(
   "Image",
   Astro.props as Record<string, any>,
@@ -21,7 +27,7 @@ validateProps(
 ---
 
 <figure
-  class="p-1.5 pb-2 my-8 group border border-neutral-200/80 dark:border-neutral-800 shadow-xs bg-neutral-50 dark:bg-neutral-900 rounded-2xl"
+  class="p-1.5 pb-2 group border border-neutral-200/80 dark:border-neutral-800 shadow-xs bg-neutral-50 dark:bg-neutral-900 rounded-2xl"
   x-data="{ 
     open: false, 
     showZoomed: false,
@@ -96,7 +102,7 @@ validateProps(
   {
     title && (
       <figcaption class="mt-2 text-center text-sm text-neutral-500 dark:text-neutral-400 font-medium whitespace-pre-line leading-relaxed px-2">
-        {title}
+        <span set:html={captionHtml} />
       </figcaption>
     )
   }

package/template/src/lib/mdx/rehype-external-links.ts

@@ -0,0 +1,57 @@
+import type { Plugin } from "unified";
+
+type HastNode = {
+  type?: string;
+  tagName?: string;
+  properties?: Record<string, unknown>;
+  children?: HastNode[];
+};
+
+function isExternalHttpLink(href: unknown): href is string {
+  return typeof href === "string" && /^https?:\/\//i.test(href);
+}
+
+function normalizeRelTokens(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value
+      .flatMap((entry) =>
+        typeof entry === "string" ? entry.split(/\s+/) : [],
+      )
+      .filter(Boolean);
+  }
+
+  if (typeof value === "string") {
+    return value.split(/\s+/).filter(Boolean);
+  }
+
+  return [];
+}
+
+function visitNodes(node: HastNode, visitor: (node: HastNode) => void): void {
+  visitor(node);
+  if (!Array.isArray(node.children)) return;
+  for (const child of node.children) {
+    visitNodes(child, visitor);
+  }
+}
+
+export const rehypeExternalLinks: Plugin<[], HastNode> = () => {
+  return (tree) => {
+    visitNodes(tree, (node) => {
+      if (node.type !== "element" || node.tagName !== "a") return;
+
+      const props = (node.properties ??= {});
+      const href = props.href;
+      if (!isExternalHttpLink(href)) return;
+
+      props.target = "_blank";
+
+      const relTokens = normalizeRelTokens(props.rel);
+      if (!relTokens.includes("noopener")) relTokens.push("noopener");
+      if (!relTokens.includes("noreferrer")) relTokens.push("noreferrer");
+      props.rel = relTokens.join(" ");
+    });
+  };
+};
+
+export default rehypeExternalLinks;

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

@@ -6,6 +6,7 @@ import { gfm } from "micromark-extension-gfm";
 import { mdxjs } from "micromark-extension-mdxjs";
 import type { Plugin } from "unified";
 import { visitParents } from "unist-util-visit-parents";
+import { transformStandaloneImageParagraphs } from "./remark-standalone-image-component";
 
 type CodeNode = {
   type: "code";
@@ -275,6 +276,7 @@ function parseComponentPreviewChildren(rawCode: string): unknown[] {
     mdastExtensions: [gfmFromMarkdown(), mdxFromMarkdown()],
   }) as Root;
 
+  transformStandaloneImageParagraphs(parsedTree);
   transformCodeBlockNodes(parsedTree);
 
   return transformPreviewChildren(

package/template/src/lib/mdx/remark-standalone-image-component.ts

@@ -0,0 +1,89 @@
+import type { Root } from "mdast";
+import type { Plugin } from "unified";
+import { visitParents } from "unist-util-visit-parents";
+
+type ParagraphNode = {
+  type: "paragraph";
+  children?: unknown[];
+};
+
+type ImageNode = {
+  type: "image";
+  url?: string | null;
+  alt?: string | null;
+  title?: string | null;
+};
+
+type ParentNode = {
+  children?: unknown[];
+};
+
+type MdxJsxAttributeNode = {
+  type: "mdxJsxAttribute";
+  name: string;
+  value: string | null;
+};
+
+type MdxJsxFlowElementNode = {
+  type: "mdxJsxFlowElement";
+  name: string;
+  attributes: MdxJsxAttributeNode[];
+  children: unknown[];
+};
+
+function createAttribute(name: string, value: string): MdxJsxAttributeNode {
+  return {
+    type: "mdxJsxAttribute",
+    name,
+    value,
+  };
+}
+
+export function transformStandaloneImageParagraphs(tree: Root): void {
+  visitParents(tree, "paragraph", (node, ancestors) => {
+    const paragraph = node as ParagraphNode;
+    if (!Array.isArray(paragraph.children) || paragraph.children.length !== 1) {
+      return;
+    }
+
+    const onlyChild = paragraph.children[0] as ImageNode;
+    if (onlyChild.type !== "image") return;
+    if (typeof onlyChild.url !== "string" || onlyChild.url.trim().length === 0) {
+      return;
+    }
+
+    const parent = ancestors[ancestors.length - 1] as ParentNode | undefined;
+    if (!Array.isArray(parent?.children)) return;
+
+    const currentIndex = parent.children.indexOf(node);
+    if (currentIndex < 0) return;
+
+    const attributes: MdxJsxAttributeNode[] = [
+      createAttribute("src", onlyChild.url),
+    ];
+
+    if (typeof onlyChild.alt === "string") {
+      attributes.push(createAttribute("alt", onlyChild.alt));
+    }
+    if (typeof onlyChild.title === "string") {
+      attributes.push(createAttribute("title", onlyChild.title));
+    }
+
+    const replacementNode: MdxJsxFlowElementNode = {
+      type: "mdxJsxFlowElement",
+      name: "Image",
+      attributes,
+      children: [],
+    };
+
+    parent.children[currentIndex] = replacementNode;
+  });
+}
+
+export const remarkStandaloneImageComponent: Plugin<[], Root> = () => {
+  return (tree) => {
+    transformStandaloneImageParagraphs(tree);
+  };
+};
+
+export default remarkStandaloneImageComponent;

package/template/src/lib/utils.ts

@@ -3,6 +3,7 @@ import remarkParse from "remark-parse";
 import remarkGfm from "remark-gfm";
 import remarkRehype from "remark-rehype";
 import rehypeStringify from "rehype-stringify";
+import rehypeExternalLinks from "./mdx/rehype-external-links";
 import path from "node:path";
 
 export function slugify(text: string): string {
@@ -25,6 +26,7 @@ export async function renderMarkdown(markdown: string): Promise<string> {
     .use(remarkParse)
     .use(remarkGfm) // GitHub Flavored Markdown (for lists, etc.)
     .use(remarkRehype, { allowDangerousHtml: false })
+    .use(rehypeExternalLinks)
     .use(rehypeStringify)
     .process(markdown);