feat(editor): add support for multi-yml files e.g. products and versions (#4513)

Author: stephencme

packages/commons/docs-loader/src/editable-docs-loader.ts

@@ -117,15 +117,20 @@ interface DocsYmlError {
 interface GetDocsYmlSuccess {
     type: "ok";
     result: string;
+    metadata: {
+        path: string;
+        defaultBranch: string;
+    };
 }
 
 export type GetDocsYmlResult = GetDocsYmlSuccess | DocsYmlError;
 
-interface UpdateDocsYmlSuccess {
+interface GetDocsYmlAndReferencesSuccess {
     type: "ok";
+    result: Map<string, string>;
 }
 
-export type UpdateDocsYmlResult = UpdateDocsYmlSuccess | DocsYmlError;
+export type GetDocsYmlAndReferencesResult = GetDocsYmlAndReferencesSuccess | DocsYmlError;
 
 export type FernConfigJsonErrors =
     | GetFernProjectErrors
@@ -157,18 +162,17 @@ export interface FernProject {
 }
 
 /**
- * The GitLoader is used to get and update docs.yml from a remote git repository.
+ * The GitLoader is used to get docs.yml and other files from a remote git repository.
  */
 export interface GitLoader {
     getFernProjectBySite(owner: string, repo: string, site: string): Promise<GetFernProjectResult>;
     getDocsYml(owner: string, repo: string, site: string, ref?: string): Promise<GetDocsYmlResult>;
-    updateDocsYml(
+    getDocsYmlAndReferences(
         owner: string,
         repo: string,
         site: string,
-        content: string,
         ref?: string
-    ): Promise<UpdateDocsYmlResult>;
+    ): Promise<GetDocsYmlAndReferencesResult>;
     getFernConfigJson(owner: string, repo: string, site: string): Promise<GetFernConfigJsonResult>;
 }
 

packages/fdr-sdk/src/navigation/versions/latest/index.ts

@@ -3,6 +3,8 @@ export * from "../../../client/generated/api/resources/navigation/resources/late
 export * from "./getChildren";
 export * from "./getPageId";
 export * from "./isApiReferenceNode";
+export * from "./isExternalProductNode";
+export * from "./isInternalProductNode";
 export * from "./isProductGroupNode";
 export * from "./isProductNode";
 export * from "./isSidebarRootNode";

packages/fdr-sdk/src/navigation/versions/latest/isExternalProductNode.ts

@@ -0,0 +1,5 @@
+import type { ExternalProductNode, NavigationNode } from ".";
+
+export function isExternalProductNode(node: NavigationNode): node is ExternalProductNode {
+    return node.type === "productLink";
+}

packages/fdr-sdk/src/navigation/versions/latest/isInternalProductNode.ts

@@ -0,0 +1,5 @@
+import type { InternalProductNode, NavigationNode } from ".";
+
+export function isInternalProductNode(node: NavigationNode): node is InternalProductNode {
+    return node.type === "product";
+}

packages/fern-dashboard/src/app/[orgName]/(visual-editor)/editor/[docsUrl]/[branch]/[...slug]/@sidebar/CreatePageButton.tsx

@@ -1,14 +1,11 @@
 "use client";
 
 import type { SerializableFoundNode } from "@fern-docs/components/navigation";
-import { useNavigation } from "@fern-docs/components/navigation";
-
 import { DashboardTooltip } from "@/components/editor/DashboardTooltip";
 import { Icon } from "@/components/icon/Icon";
 import { Button } from "@/components/ui/button";
 import { useEditingDisabled } from "@/hooks/useEditingDisabled";
 import { useGitPrInfo } from "@/providers/GitPRContext";
-import { UI_MESSAGES } from "@/utils/messages";
 
 import { CreateClientPage } from "./CreateClientPage";
 
@@ -20,24 +17,17 @@ interface CreatePageButtonProps {
 export function CreatePageButton({ baseFoundNode }: CreatePageButtonProps) {
     const { prStatus } = useGitPrInfo();
     const isEditingDisabled = useEditingDisabled();
-    const navigation = useNavigation();
-
-    // LIMITATION: Page creation is not supported for multi-product or multi-version docs
-    // These docs have separate docs.yml files for each product/version, and we would need to
-    // determine which specific file to modify. This is a complex operation that's not yet supported.
-    const canEditNavigation = navigation.canDirectlyEditDocsYmlNavigation;
 
-    const tooltipContent = !canEditNavigation
-        ? UI_MESSAGES.NAVIGATION_EDITS_NOT_SUPPORTED_MULTI_DOCS_YML
-        : isEditingDisabled && prStatus === "merged"
-          ? "Cannot create page - PR has already been merged"
-          : isEditingDisabled && prStatus === "closed"
-            ? "Cannot create page - PR has been closed"
-            : undefined;
+    const tooltipContent =
+        isEditingDisabled && prStatus === "merged"
+            ? "Cannot create page - PR has already been merged"
+            : isEditingDisabled && prStatus === "closed"
+              ? "Cannot create page - PR has been closed"
+              : undefined;
 
     return (
         <DashboardTooltip content={tooltipContent}>
-            <CreateClientPage baseFoundNode={baseFoundNode} disabled={isEditingDisabled || !canEditNavigation}>
+            <CreateClientPage baseFoundNode={baseFoundNode} disabled={isEditingDisabled}>
                 <Button
                     className="mb-2 flex w-full items-center justify-center gap-2 self-stretch rounded-lg border border-dashed border-[var(--grayscale-a6)] p-2 text-sm text-[var(--grayscale-a11)] hover:bg-[var(--grayscale-a3)] hover:text-[var(--grayscale-a12)]"
                     variant="ghost"

packages/fern-dashboard/src/app/[orgName]/(visual-editor)/editor/[docsUrl]/[branch]/[...slug]/@sidebar/PageSidebar.tsx

@@ -2,7 +2,7 @@
 
 import type { DangerousTransmittableDocsLoaderData } from "@fern-api/docs-loader";
 import { getIsSidebarFixed, getIsSingleOverviewPage } from "@fern-api/docs-utils";
-import type * as FernNavigation from "@fern-api/fdr-sdk/navigation";
+import * as FernNavigation from "@fern-api/fdr-sdk/navigation";
 import {
     type ClientPageDataDependencies,
     type ResolvedPageData,
@@ -88,7 +88,11 @@ export default function PageSidebar({
                     sidebarRootNodeId={found.sidebar?.id}
                     tabId={found.currentTab?.id}
                     productId={found.currentProduct?.productId}
-                    productSlug={found.currentProduct?.slug}
+                    productSlug={
+                        found.currentProduct && FernNavigation.isInternalProductNode(found.currentProduct)
+                            ? found.currentProduct.slug
+                            : undefined
+                    }
                     versionId={found.currentVersion?.versionId}
                     versionSlug={found.currentVersion?.slug}
                     variantId={found.currentVariant?.variantId}
@@ -114,12 +118,7 @@ export default function PageSidebar({
                         renderOptions={{
                             forceClientRender: true,
                             wrapPageNode: (node, component) => (
-                                <DeletablePageNodeWrapper
-                                    node={node}
-                                    component={component}
-                                    icon={undefined}
-                                    depth={0}
-                                />
+                                <DeletablePageNodeWrapper node={node} component={component} />
                             ),
                             wrapSectionNode: (node, trigger) => <SidebarSectionWithMenu node={node} trigger={trigger} />
                         }}

packages/fern-dashboard/src/app/[orgName]/(visual-editor)/editor/[docsUrl]/[branch]/[...slug]/PageNode.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import type * as FernNavigation from "@fern-api/fdr-sdk/navigation";
+import * as FernNavigation from "@fern-api/fdr-sdk/navigation";
 import {
     type ClientPageDataDependencies,
     type ResolvedPageData,
@@ -88,7 +88,11 @@ export default function PageNode(props: PageNode.Props) {
                 sidebarRootNodeId={found.sidebar?.id}
                 tabId={found.currentTab?.id}
                 productId={found.currentProduct?.productId}
-                productSlug={found.currentProduct?.slug}
+                productSlug={
+                    found.currentProduct && FernNavigation.isInternalProductNode(found.currentProduct)
+                        ? found.currentProduct.slug
+                        : undefined
+                }
                 versionId={found.currentVersion?.versionId}
                 versionSlug={found.currentVersion?.slug}
                 variantId={found.currentVariant?.variantId}

packages/fern-dashboard/src/app/[orgName]/(visual-editor)/editor/[docsUrl]/[branch]/layout.tsx

@@ -62,17 +62,17 @@ export default async function EditorLayout({
     const githubLoader = new GitHubLoader(githubUrl);
 
     // Use the repo's default branch by passing preferDefaultBranch=true
-    const docsYmlResult = await githubLoader.getDocsYml(
+    const docsYmlAndReferences = await githubLoader.getDocsYmlAndReferences(
         sourceRepo.owner,
         sourceRepo.repo,
         docsUrl,
         branch, // fallback branch if default branch logic fails
         true // preferDefaultBranch = true
     );
-    const initialDocsYmlContent = docsYmlResult.type === "ok" ? docsYmlResult.result : null;
+    const latestDocsYmlAndReferences = docsYmlAndReferences.type === "ok" ? docsYmlAndReferences.result : null;
 
-    if (docsYmlResult.type !== "ok") {
-        console.error(docsYmlResult.error);
+    if (docsYmlAndReferences.type !== "ok") {
+        console.error(docsYmlAndReferences.error);
     }
 
     return (
@@ -93,7 +93,7 @@ export default async function EditorLayout({
                                 branchName={branch}
                                 orgName={orgName}
                                 docsUrl={docsUrl}
-                                initialDocsYmlContent={initialDocsYmlContent}
+                                latestDocsYmlAndReferences={latestDocsYmlAndReferences}
                             >
                                 <CurrentPageProvider>
                                     <ClientMDXProvider>

packages/fern-dashboard/src/app/services/dal/github/createBranchIfNotExists.ts

@@ -105,6 +105,7 @@ export default async function createBranchIfNotExists(request: {
             response
         };
     } catch (error) {
+        console.error("[createBranchIfNotExists] Failed to create branch:", error);
         return {
             success: false,
             error: `Unknown error occurred: ${error}` // TODO: Add error message