feat(docs): add highlight prop with range syntax to snippet components (#6106)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Catherine Deskur <[email protected]>
Co-authored-by: Catherine Deskur <[email protected]>
Co-authored-by: chdeskur <[email protected]>

Author: devin-ai-integration[bot]

packages/fern-docs/bundle/package.json

@@ -119,6 +119,7 @@
     "motion": "^12.4.7",
     "next": "catalog:",
     "next-themes": "^0.4.4",
+    "parse-numeric-range": "^1.3.0",
     "posthog-js": "^1.298.0",
     "pretty-bytes": "^6.1.1",
     "qs": "catalog:",

packages/fern-docs/bundle/src/mdx/components/snippets/EndpointRequestSnippet.tsx

@@ -15,7 +15,8 @@ export function EndpointRequestSnippet({
     endpointDefinition,
     slugs,
     lang,
-    className
+    className,
+    highlight
 }: {
     /**
      * The endpoint locator to use for the request snippet.
@@ -35,6 +36,10 @@ export function EndpointRequestSnippet({
     slugs?: string[];
     lang?: string;
     className?: string;
+    /**
+     * Sets the lines to highlight
+     */
+    highlight?: number | number[];
 }) {
     if (endpointDefinition == null) {
         return null;
@@ -47,6 +52,7 @@ export function EndpointRequestSnippet({
             example={example}
             className={className}
             lang={lang ?? "en"}
+            highlight={highlight}
         />
     );
 }
@@ -56,13 +62,15 @@ function EndpointRequestSnippetInternal({
     example,
     slugs,
     className,
-    lang
+    lang,
+    highlight
 }: {
     endpoint: ApiDefinition.EndpointDefinition;
     example: string | undefined;
     slugs: string[];
     lang: string;
     className?: string;
+    highlight?: number | number[];
 }): ReactElement<any> | null {
     const slug = useCurrentSlug(slugs);
     const { selectedExample, selectedExampleKey, availableLanguages, setSelectedExampleKey } = useExampleSelection(
@@ -114,6 +122,7 @@ function EndpointRequestSnippetInternal({
                 language={selectedExampleKey.language}
                 json={EMPTY_OBJECT}
                 scrollAreaStyle={{ maxHeight: "500px" }}
+                highlight={highlight}
             />
         </div>
     );

packages/fern-docs/bundle/src/mdx/components/snippets/EndpointResponseSnippet.tsx

@@ -10,7 +10,8 @@ export function EndpointResponseSnippet({
     endpointDefinition,
     slug,
     className,
-    lang
+    lang,
+    highlight
 }: {
     /**
      * The endpoint locator to use for the request snippet.
@@ -30,6 +31,10 @@ export function EndpointResponseSnippet({
     slug: string;
     className?: string;
     lang?: string;
+    /**
+     * Sets the lines to highlight
+     */
+    highlight?: number | number[];
 }) {
     if (endpointDefinition == null) {
         return null;
@@ -42,6 +47,7 @@ export function EndpointResponseSnippet({
             slug={slug}
             className={className}
             lang={lang ?? "en"}
+            highlight={highlight}
         />
     );
 }
@@ -51,13 +57,15 @@ function EndpointResponseSnippetInternal({
     example,
     slug,
     className,
-    lang
+    lang,
+    highlight
 }: {
     slug: string;
     endpoint: EndpointDefinition;
     example: string | undefined;
     className?: string;
     lang: string;
+    highlight?: number | number[];
 }) {
     const { selectedExample } = useExampleSelection(endpoint, example);
 
@@ -81,6 +89,7 @@ function EndpointResponseSnippetInternal({
                 slug={slug}
                 isResponse
                 lang={lang}
+                highlight={highlight}
             />
         </div>
     );

packages/fern-docs/bundle/src/mdx/components/snippets/SchemaSnippet.tsx

@@ -23,9 +23,13 @@ type SchemaSnippetProps = {
      */
     title?: string;
     className?: string;
+    /**
+     * Line numbers to highlight. Supports range syntax like `highlight={[1-5, 7, 9]}`.
+     */
+    highlight?: number | number[];
 };
 
-export function SchemaSnippet({ typeDefinition, types, lang, title, className }: SchemaSnippetProps) {
+export function SchemaSnippet({ typeDefinition, types, lang, title, className, highlight }: SchemaSnippetProps) {
     const language = lang ?? "en";
 
     const example = useMemo(() => {
@@ -50,6 +54,7 @@ export function SchemaSnippet({ typeDefinition, types, lang, title, className }:
                 json={example}
                 scrollAreaStyle={{ maxHeight: "500px" }}
                 lang={language}
+                highlight={highlight}
             />
         </div>
     );

packages/fern-docs/bundle/src/mdx/components/snippets/WebhookPayloadSnippet.tsx

@@ -7,7 +7,8 @@ export function WebhookPayloadSnippet({
     webhookDefinition,
     slug,
     className,
-    lang
+    lang,
+    highlight
 }: {
     /**
      * The webhook locator to use for the payload snippet.
@@ -24,6 +25,10 @@ export function WebhookPayloadSnippet({
     slug: string | undefined;
     className?: string;
     lang?: string;
+    /**
+     * Sets the lines to highlight
+     */
+    highlight?: number | number[];
 }) {
     if (webhookDefinition == null) {
         return null;
@@ -35,6 +40,7 @@ export function WebhookPayloadSnippet({
             slug={slug}
             className={className}
             lang={lang ?? "en"}
+            highlight={highlight}
         />
     );
 }
@@ -43,12 +49,14 @@ function WebhookPayloadSnippetInternal({
     webhook,
     slug,
     className,
-    lang
+    lang,
+    highlight
 }: {
     slug: string | undefined;
     webhook: ApiDefinition.WebhookDefinition;
     className?: string;
     lang: string;
+    highlight?: number | number[];
 }) {
     const example = webhook.examples?.[0];
 
@@ -74,6 +82,7 @@ function WebhookPayloadSnippetInternal({
                 scrollAreaStyle={{ maxHeight: "500px" }}
                 slug={slug}
                 lang={lang}
+                highlight={highlight}
             />
         </div>
     );

packages/fern-docs/bundle/src/mdx/plugins/expand-highlight-ranges.test.ts

@@ -0,0 +1,129 @@
+import type { Hast, MdxJsxAttribute } from "@fern-docs/mdx";
+import { expandHighlightRanges } from "./expand-highlight-ranges";
+
+function createMockNode(highlightValue: string): Hast.MdxJsxElement {
+    return {
+        type: "mdxJsxFlowElement",
+        name: "TestComponent",
+        attributes: [
+            {
+                type: "mdxJsxAttribute",
+                name: "highlight",
+                value: {
+                    type: "mdxJsxAttributeValueExpression",
+                    value: highlightValue,
+                    data: {}
+                }
+            }
+        ],
+        children: []
+    };
+}
+
+function getHighlightValue(node: Hast.MdxJsxElement): string | undefined {
+    const attr = node.attributes.find(
+        (a): a is MdxJsxAttribute => a.type === "mdxJsxAttribute" && a.name === "highlight"
+    );
+    if (attr?.value && typeof attr.value === "object" && attr.value.type === "mdxJsxAttributeValueExpression") {
+        return attr.value.value;
+    }
+    return undefined;
+}
+
+describe("expandHighlightRanges", () => {
+    it("should expand a simple range", () => {
+        const node = createMockNode("[1-5]");
+        expandHighlightRanges(node);
+        expect(getHighlightValue(node)).toBe("[1, 2, 3, 4, 5]");
+    });
+
+    it("should expand a range with individual numbers", () => {
+        const node = createMockNode("[1-3, 7, 9]");
+        expandHighlightRanges(node);
+        expect(getHighlightValue(node)).toBe("[1, 2, 3, 7, 9]");
+    });
+
+    it("should expand multiple ranges", () => {
+        const node = createMockNode("[1-3, 5-7]");
+        expandHighlightRanges(node);
+        expect(getHighlightValue(node)).toBe("[1, 2, 3, 5, 6, 7]");
+    });
+
+    it("should not modify arrays without ranges", () => {
+        const node = createMockNode("[1, 2, 3]");
+        expandHighlightRanges(node);
+        expect(getHighlightValue(node)).toBe("[1, 2, 3]");
+    });
+
+    it("should handle whitespace in the expression", () => {
+        const node = createMockNode("[ 1-3 , 5 ]");
+        expandHighlightRanges(node);
+        expect(getHighlightValue(node)).toBe("[1, 2, 3, 5]");
+    });
+
+    it("should handle out-of-order list", () => {
+        const node = createMockNode("[ 5, 1-3 ]");
+        expandHighlightRanges(node);
+        expect(getHighlightValue(node)).toBe("[5, 1, 2, 3]");
+    });
+
+    it("should not modify non-highlight attributes", () => {
+        const node: Hast.MdxJsxElement = {
+            type: "mdxJsxFlowElement",
+            name: "TestComponent",
+            attributes: [
+                {
+                    type: "mdxJsxAttribute",
+                    name: "otherProp",
+                    value: {
+                        type: "mdxJsxAttributeValueExpression",
+                        value: "[1-5]",
+                        data: {}
+                    }
+                }
+            ],
+            children: []
+        };
+        expandHighlightRanges(node);
+        const attr = node.attributes.find(
+            (a): a is MdxJsxAttribute => a.type === "mdxJsxAttribute" && a.name === "otherProp"
+        );
+        if (attr?.value && typeof attr.value === "object" && attr.value.type === "mdxJsxAttributeValueExpression") {
+            expect(attr.value.value).toBe("[1-5]");
+        }
+    });
+
+    it("should handle string attribute values", () => {
+        const node: Hast.MdxJsxElement = {
+            type: "mdxJsxFlowElement",
+            name: "TestComponent",
+            attributes: [
+                {
+                    type: "mdxJsxAttribute",
+                    name: "highlight",
+                    value: "some-string"
+                }
+            ],
+            children: []
+        };
+        expandHighlightRanges(node);
+        const attr = node.attributes.find(
+            (a): a is MdxJsxAttribute => a.type === "mdxJsxAttribute" && a.name === "highlight"
+        );
+        expect(attr?.value).toBe("some-string");
+    });
+
+    it("should create valid estree for the expanded array", () => {
+        const node = createMockNode("[1-3]");
+        expandHighlightRanges(node);
+        const attr = node.attributes.find(
+            (a): a is MdxJsxAttribute => a.type === "mdxJsxAttribute" && a.name === "highlight"
+        );
+        if (attr?.value && typeof attr.value === "object" && attr.value.type === "mdxJsxAttributeValueExpression") {
+            const estree = attr.value.data?.estree;
+            expect(estree).toBeDefined();
+            expect(estree?.type).toBe("Program");
+            expect(estree?.body[0]?.type).toBe("ExpressionStatement");
+        }
+    });
+});

packages/fern-docs/bundle/src/mdx/plugins/expand-highlight-ranges.ts

@@ -0,0 +1,48 @@
+import type { Hast } from "@fern-docs/mdx";
+import parseNumericRange from "parse-numeric-range";
+
+/**
+ * Expands range syntax in the `highlight` attribute of MDX JSX elements.
+ * For example, `highlight={[1-5, 7, 9]}` becomes `highlight={[1, 2, 3, 4, 5, 7, 9]}`.
+ *
+ * This is necessary because JSX expressions like `[1-5, 7, 9]` would normally be
+ * evaluated as JavaScript where `1-5` becomes `-4`. This function intercepts the
+ * raw expression string before JavaScript evaluation and rewrites it.
+ */
+export function expandHighlightRanges(node: Hast.MdxJsxElement): void {
+    for (const attr of node.attributes) {
+        if (attr.type !== "mdxJsxAttribute" || attr.name !== "highlight") {
+            continue;
+        }
+
+        if (typeof attr.value === "object" && attr.value?.type === "mdxJsxAttributeValueExpression") {
+            const rawExpr = attr.value.value;
+            if (/\[\s*[\d\s,-]+\s*\]/.test(rawExpr) && rawExpr.includes("-")) {
+                const expanded = parseNumericRange(rawExpr.replace(/[[\]]/g, ""));
+                attr.value = {
+                    type: "mdxJsxAttributeValueExpression",
+                    value: `[${expanded.join(", ")}]`,
+                    data: {
+                        estree: {
+                            type: "Program",
+                            body: [
+                                {
+                                    type: "ExpressionStatement",
+                                    expression: {
+                                        type: "ArrayExpression",
+                                        elements: expanded.map((n) => ({
+                                            type: "Literal",
+                                            value: n,
+                                            raw: String(n)
+                                        }))
+                                    }
+                                }
+                            ],
+                            sourceType: "module"
+                        }
+                    }
+                };
+            }
+        }
+    }
+}

packages/fern-docs/bundle/src/mdx/plugins/rehype-endpoint-example-snippets.ts

@@ -11,6 +11,7 @@ import {
     unknownToMdxJsxAttribute,
     visit
 } from "@fern-docs/mdx";
+import { expandHighlightRanges } from "./expand-highlight-ranges";
 
 /**
  * The code below copies the `example` prop of an
@@ -49,6 +50,7 @@ export const rehypeEndpointExampleSnippets: Unified.Plugin<[{ loader: DocsLoader
 
             // check that the current node is a request or response snippet
             if (isRequestSnippet || isResponseSnippet) {
+                expandHighlightRanges(node);
                 const { props } = hastMdxJsxElementHastToProps(node);
 
                 // cannot parse non-string endpoint prop