docs: external sidebar links, filled navbar button, tab slug overrides (

#3034) * external link * fix bugs * fix fdr upgrade renames
fern-api · Feb 22, 2024 · a4e45c5 · a4e45c5
1 parent 3d91632
commit a4e45c5
Show file tree

Hide file tree

Showing 21 changed files with 110 additions and 87 deletions.
diff --git a/.pnp.cjs b/.pnp.cjs
diff --git a/...50.1-1-g1f0f637-985a50f2f4-32eb06bac6.zip → ...50.8-1-gace1ff5-e436b1d2bc-32de6d37ef.zip b/...50.1-1-g1f0f637-985a50f2f4-32eb06bac6.zip → ...50.8-1-gace1ff5-e436b1d2bc-32de6d37ef.zip
diff --git a/...nfig-npm-0.0.75-91c3b78e3e-3629548884.zip → ...nfig-npm-0.0.76-8592dd5cfc-97fbaacd7a.zip b/...nfig-npm-0.0.75-91c3b78e3e-3629548884.zip → ...nfig-npm-0.0.76-8592dd5cfc-97fbaacd7a.zip
diff --git a/fern/apis/docs-config/definition/docs.yml b/fern/apis/docs-config/definition/docs.yml
@@ -33,6 +33,7 @@ types:
     properties:
       display-name: string
       icon: string
+      slug: optional<string>
 
   DocsInstances:
     properties:
@@ -135,6 +136,7 @@ types:
       - PageConfiguration
       - SectionConfiguration
       - ApiSectionConfiguration
+      - LinkConfiguration
 
   LogoConfiguration:
     properties:
@@ -328,15 +330,15 @@ types:
 
   NavbarLink:
     union:
-      primary: NavbarPrimaryLink
-      secondary: NavbarSecondaryLink
+      filled: LinkConfiguration
+      outlined: LinkConfiguration
+      minimal: LinkConfiguration
 
-  NavbarPrimaryLink:
-    properties:
-      url: string
-      text: string
+      # deprecated
+      primary: LinkConfiguration # use `outlined` instead
+      secondary: LinkConfiguration # use `minimal` instead
 
-  NavbarSecondaryLink:
+  LinkConfiguration:
     properties:
       url: string
       text: string

diff --git a/packages/cli/config-management/docs-configuration/package.json b/packages/cli/config-management/docs-configuration/package.json
@@ -29,10 +29,10 @@
   "dependencies": {
     "@fern-api/config-management-commons": "workspace:*",
     "@fern-api/core-utils": "workspace:*",
-    "@fern-api/fdr-sdk": "0.50.1-1-g1f0f637",
+    "@fern-api/fdr-sdk": "0.50.8-1-gace1ff5",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/task-context": "workspace:*",
-    "@fern-fern/docs-config": "0.0.75",
+    "@fern-fern/docs-config": "0.0.76",
     "js-yaml": "^4.1.0",
     "tinycolor2": "^1.6.0"
   },

diff --git a/packages/cli/config-management/docs-configuration/src/ParsedDocsConfiguration.ts b/packages/cli/config-management/docs-configuration/src/ParsedDocsConfiguration.ts
@@ -125,7 +125,11 @@ export interface TabbedNavigation {
     layout: DocsNavigationItem[];
 }
 
-export type DocsNavigationItem = DocsNavigationItem.Page | DocsNavigationItem.Section | DocsNavigationItem.ApiSection;
+export type DocsNavigationItem =
+    | DocsNavigationItem.Page
+    | DocsNavigationItem.Section
+    | DocsNavigationItem.ApiSection
+    | DocsNavigationItem.Link;
 
 export declare namespace DocsNavigationItem {
     export interface Page {
@@ -152,6 +156,12 @@ export declare namespace DocsNavigationItem {
         snippetsConfiguration: SnippetsConfiguration | undefined;
     }
 
+    export interface Link {
+        type: "link";
+        text: string;
+        url: string;
+    }
+
     export interface SnippetsConfiguration {
         python: string | undefined;
         typescript: string | undefined;

diff --git a/packages/cli/config-management/docs-configuration/src/getAllPages.ts b/packages/cli/config-management/docs-configuration/src/getAllPages.ts
@@ -64,6 +64,7 @@ export async function getAllPagesFromNavigationItem({
 }): Promise<Record<RelativeFilePath, string>> {
     switch (item.type) {
         case "apiSection":
+        case "link":
             return {};
         case "page":
             return {

diff --git a/packages/cli/config-management/docs-configuration/src/getReferencedApiSections.ts b/packages/cli/config-management/docs-configuration/src/getReferencedApiSections.ts
@@ -77,8 +77,13 @@ export function visitDocsNavigationItem({
         case "apiSection":
             collector.collect(item);
             return;
-        case "page":
         case "section":
+            item.contents.forEach((subItem) => {
+                visitDocsNavigationItem({ item: subItem, collector });
+            });
+            return;
+        case "page":
+        case "link":
             return;
         default:
             assertNever(item);

diff --git a/packages/cli/config-management/docs-configuration/src/parseDocsConfiguration.ts b/packages/cli/config-management/docs-configuration/src/parseDocsConfiguration.ts
@@ -131,7 +131,7 @@ export async function parseDocsConfiguration({
         favicon,
         backgroundImage,
         colors: convertColorsConfiguration(colors ?? {}, context),
-        navbarLinks: navbarLinks != null ? convertNavbarLinks(navbarLinks) : undefined,
+        navbarLinks,
         typography,
         layout: convertLayoutConfig(layout),
         css,
@@ -503,6 +503,13 @@ async function convertNavigationItem({
                 rawConfig.snippets != null ? convertSnippetsConfiguration({ rawConfig: rawConfig.snippets }) : undefined
         };
     }
+    if (isRawLinkConfig(rawConfig)) {
+        return {
+            type: "link",
+            text: rawConfig.text,
+            url: rawConfig.url
+        };
+    }
     assertNever(rawConfig);
 }
 
@@ -534,6 +541,11 @@ function isRawApiSectionConfig(item: RawDocs.NavigationItem): item is RawDocs.Ap
     return (item as RawDocs.ApiSectionConfiguration).api != null;
 }
 
+function isRawLinkConfig(item: RawDocs.NavigationItem): item is RawDocs.LinkConfiguration {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    return (item as RawDocs.LinkConfiguration).url != null;
+}
+
 async function convertImageReference({
     rawImageReference,
     absoluteFilepathToDocsConfig
@@ -549,27 +561,6 @@ async function convertImageReference({
     };
 }
 
-function convertNavbarLinks(rawConfig: RawDocs.NavbarLink[]): DocsV1Write.NavbarLink[] {
-    return rawConfig.map((rawNavbarLink) => {
-        switch (rawNavbarLink.type) {
-            case "primary":
-                return {
-                    type: "primary",
-                    text: rawNavbarLink.text,
-                    url: rawNavbarLink.url
-                };
-            case "secondary":
-                return {
-                    type: "secondary",
-                    text: rawNavbarLink.text,
-                    url: rawNavbarLink.url
-                };
-            default:
-                assertNever(rawNavbarLink);
-        }
-    });
-}
-
 async function resolveFilepath({
     rawUnresolvedFilepath,
     absolutePath

diff --git a/packages/cli/docs-preview/package.json b/packages/cli/docs-preview/package.json
@@ -29,13 +29,13 @@
   "dependencies": {
     "@fern-api/core-utils": "workspace:*",
     "@fern-api/docs-configuration": "workspace:*",
-    "@fern-api/fdr-sdk": "0.50.1-1-g1f0f637",
+    "@fern-api/fdr-sdk": "0.50.8-1-gace1ff5",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/ir-generator": "workspace:*",
     "@fern-api/register": "workspace:*",
     "@fern-api/task-context": "workspace:*",
     "@fern-api/workspace-loader": "workspace:*",
-    "@fern-fern/docs-config": "0.0.75",
+    "@fern-fern/docs-config": "0.0.76",
     "cors": "^2.8.5",
     "express": "^4.18.2",
     "uuid": "^9.0.1"

diff --git a/packages/cli/docs-preview/src/previewDocs.ts b/packages/cli/docs-preview/src/previewDocs.ts
@@ -218,7 +218,8 @@ async function convertNavigationConfig({
                                         apiCollector
                                     })
                                 )
-                            )
+                            ),
+                            urlSlugOverride: tabConfig.slug
                         };
                     })
                 )
@@ -370,6 +371,12 @@ async function convertNavigationItem({
                 showErrors: item.showErrors
             };
         }
+        case "link":
+            return {
+                type: "link",
+                title: item.text,
+                url: item.url
+            };
         default:
             assertNever(item);
     }

diff --git a/packages/cli/generation/remote-generation/remote-workspace-runner/package.json b/packages/cli/generation/remote-generation/remote-workspace-runner/package.json
@@ -32,7 +32,7 @@
     "@fern-api/core": "workspace:*",
     "@fern-api/core-utils": "workspace:*",
     "@fern-api/docs-configuration": "workspace:*",
-    "@fern-api/fdr-sdk": "0.50.1-1-g1f0f637",
+    "@fern-api/fdr-sdk": "0.50.8-1-gace1ff5",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/generators-configuration": "workspace:*",
     "@fern-api/ir-generator": "workspace:*",
@@ -42,7 +42,7 @@
     "@fern-api/register": "workspace:*",
     "@fern-api/task-context": "workspace:*",
     "@fern-api/workspace-loader": "workspace:*",
-    "@fern-fern/docs-config": "0.0.75",
+    "@fern-fern/docs-config": "0.0.76",
     "@fern-fern/fiddle-sdk": "^0.0.411",
     "axios": "^0.28.0",
     "chalk": "^5.0.1",

diff --git a/packages/cli/generation/remote-generation/remote-workspace-runner/src/publishDocs.ts b/packages/cli/generation/remote-generation/remote-workspace-runner/src/publishDocs.ts
@@ -497,7 +497,8 @@ async function convertUnversionedNavigationConfig({
                                         version
                                     })
                                 )
-                            )
+                            ),
+                            urlSlugOverride: tabConfig.slug
                         };
                     })
                 )
@@ -702,6 +703,12 @@ async function convertNavigationItem({
                 showErrors: item.showErrors
             };
         }
+        case "link":
+            return {
+                type: "link",
+                title: item.text,
+                url: item.url
+            };
         default:
             assertNever(item);
     }

diff --git a/packages/cli/init/package.json b/packages/cli/init/package.json
@@ -36,7 +36,7 @@
     "@fern-api/task-context": "workspace:*",
     "@fern-api/yaml-formatter": "workspace:*",
     "@fern-api/yaml-schema": "workspace:*",
-    "@fern-fern/docs-config": "0.0.75",
+    "@fern-fern/docs-config": "0.0.76",
     "axios": "^0.28.0",
     "chalk": "^5.0.1",
     "fs-extra": "^11.1.1",

diff --git a/packages/cli/register/package.json b/packages/cli/register/package.json
@@ -31,7 +31,7 @@
     "@fern-api/config-management-commons": "workspace:*",
     "@fern-api/core": "workspace:*",
     "@fern-api/core-utils": "workspace:*",
-    "@fern-api/fdr-sdk": "0.50.1-1-g1f0f637",
+    "@fern-api/fdr-sdk": "0.50.8-1-gace1ff5",
     "@fern-api/ir-generator": "workspace:*",
     "@fern-api/ir-sdk": "workspace:*",
     "@fern-api/task-context": "workspace:*",