fix(docs): prevent API reference title from inheriting child tag description overview page (#14870)

* fix(docs): prevent API reference title from inheriting child tag description overview page

When tag-description-pages is enabled, child apiPackage nodes get
overviewPageIds from their tag descriptions. Previously, the parent
API reference node would inherit the first child's overviewPageId,
making the top-level API reference title clickable (navigating to a
folder's tag description page). This was undesirable — the folder
overview pages belong to the individual tag sections, not the parent.

Now the inheritance is skipped when tagDescriptionPages is enabled,
keeping the top-level API reference title as a non-clickable header.

Co-Authored-By: tristan.declarin <tristan.declarin@buildwithfern.com>

* test(docs): add test for overviewPageId inheritance guard with tag-description-pages

Co-Authored-By: tristan.declarin <tristan.declarin@buildwithfern.com>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: tristan.declarin <tristan.declarin@buildwithfern.com>

Author: devin-ai-integration[bot]

packages/cli/docs-resolver/src/ApiReferenceNodeConverter.ts

@@ -126,14 +126,12 @@ export class ApiReferenceNodeConverter {
             this.#idgen
         ).orUndefined();
 
-        // When no explicit overview is set, inherit the first apiPackage child's overview page (e.g., tag description).
-        // This works for both flattened and non-flattened cases:
-        // - Flattened: The section will inherit this overview page via DocsDefinitionResolver.toSectionNode()
-        // - Non-flattened: The API Reference itself will show the tag description when clicked
-        // We search through all children to find an apiPackage with an overviewPageId, rather than assuming
-        // the first child is an apiPackage (which may not be true when endpoints are explicitly listed in the layout).
+        // When no explicit overview is set and tag-description-pages is NOT enabled,
+        // inherit the first apiPackage child's overview page. When tag-description-pages
+        // IS enabled, the child overview pages belong to the individual tag sections and
+        // should not bubble up to make the top-level API reference title clickable.
         let overviewPageId = this.#overviewPageId;
-        if (overviewPageId == null) {
+        if (overviewPageId == null && !this.apiSection.tagDescriptionPages) {
             const apiPackageWithOverview = this.#children.find(
                 (child): child is FernNavigation.V1.ApiPackageNode =>
                     child.type === "apiPackage" && child.overviewPageId != null

packages/cli/docs-resolver/src/__test__/tag-description-pages.test.ts

@@ -101,6 +101,108 @@ describe("tag-description-pages", () => {
         expect(apiSection.tagDescriptionPages).toMatchSnapshot("tag-description-pages-disabled");
     });
 
+    describe("overviewPageId inheritance", () => {
+        it("does not inherit child tag overviewPageId when tag-description-pages is enabled", async () => {
+            const docsWorkspace = await loadDocsWorkspace({
+                fernDirectory: FIXTURE_DIR,
+                context
+            });
+
+            if (docsWorkspace == null) {
+                throw new Error("Workspace is null");
+            }
+
+            const parsedDocsConfig = await parseDocsConfiguration({
+                rawDocsConfiguration: docsWorkspace.config,
+                context,
+                absolutePathToFernFolder: docsWorkspace.absoluteFilePath,
+                absoluteFilepathToDocsConfig: docsWorkspace.absoluteFilepathToDocsConfig
+            });
+
+            if (parsedDocsConfig.navigation.type !== "untabbed") {
+                throw new Error("Expected untabbed navigation");
+            }
+
+            if (parsedDocsConfig.navigation.items[0]?.type !== "apiSection") {
+                throw new Error("Expected apiSection");
+            }
+
+            const apiSection = parsedDocsConfig.navigation.items[0];
+            expect(apiSection.tagDescriptionPages).toBe(true);
+
+            const result = await loadAPIWorkspace({
+                absolutePathToWorkspace: FIXTURE_DIR,
+                context,
+                cliVersion: "0.0.0",
+                workspaceName: undefined
+            });
+
+            if (!result.didSucceed) {
+                throw new Error("API workspace failed to load");
+            }
+
+            const apiWorkspace = await result.workspace.toFernWorkspace({ context });
+            const slug = FernNavigation.V1.SlugGenerator.init("/docs");
+
+            const ir = generateIntermediateRepresentation({
+                workspace: apiWorkspace,
+                audiences: { type: "all" },
+                generationLanguage: undefined,
+                keywords: undefined,
+                smartCasing: false,
+                exampleGeneration: { disabled: false },
+                readme: undefined,
+                version: undefined,
+                packageName: undefined,
+                context,
+                sourceResolver: new SourceResolverImpl(context, apiWorkspace)
+            });
+
+            const apiDefinition = convertIrToApiDefinition({
+                ir,
+                apiDefinitionId: "test-api-id",
+                context
+            });
+
+            const openApiTags: Record<string, { id: string; description: string | undefined }> = {
+                pet: { id: "pet", description: "Everything about your Pets" },
+                store: { id: "store", description: "Access to Petstore orders" },
+                user: { id: "user", description: "Operations about user" }
+            };
+
+            const converter = new ApiReferenceNodeConverter(
+                apiSection,
+                apiDefinition,
+                slug,
+                docsWorkspace,
+                context,
+                new Map(),
+                new Map(),
+                new Map(),
+                NodeIdGenerator.init(),
+                new Map(),
+                apiWorkspace,
+                undefined,
+                undefined,
+                openApiTags
+            );
+
+            const node = converter.get();
+
+            // The top-level API reference should NOT inherit a child tag's overviewPageId
+            // when tag-description-pages is enabled. Each tag keeps its own overview page;
+            // the parent title should remain non-clickable.
+            expect(node.overviewPageId).toBeUndefined();
+            expect(node.type).toBe("apiReference");
+
+            // Verify that child apiPackage nodes DO have overviewPageIds (tag description pages)
+            const childrenWithOverview = node.children.filter(
+                (child) => child.type === "apiPackage" && child.overviewPageId != null
+            );
+            expect(childrenWithOverview.length).toBeGreaterThan(0);
+        });
+    });
+
     describe("tag description content preservation", () => {
         it("does not escape curly braces or angle brackets in tag descriptions", async () => {
             const docsWorkspace = await loadDocsWorkspace({