refactor: hide filesv2 from static props

packages/fern-docs/bundle/next.config.mjs

@@ -10,6 +10,7 @@ const isTrailingSlashEnabled =
   process.env.TRAILING_SLASH === "1" ||
   process.env.NEXT_PUBLIC_TRAILING_SLASH === "1";
 
+// TODO: move this to a shared location (this is copied in @fern-docs/ui FernImage.tsx)
 const DOCS_FILES_ALLOWLIST = [
   {
     protocol: "https",

packages/fern-docs/bundle/src/server/withInitialProps.ts

@@ -21,7 +21,9 @@ import { addLeadingSlash, getRedirectForPath } from "@fern-docs/utils";
 import { SidebarTab } from "@fern-platform/fdr-utils";
 import { GetServerSidePropsResult, Redirect } from "next";
 import { ComponentProps } from "react";
+import { UnreachableCaseError } from "ts-essentials";
 import urlJoin from "url-join";
+import { LogoImageData } from "../../../ui/src/atoms";
 import { DocsLoader } from "./DocsLoader";
 import { getAuthState } from "./auth/getAuthState";
 import { getReturnToQueryParam } from "./auth/return-to";
@@ -295,6 +297,29 @@ export async function withInitialProps({
       pruneNavigationPredicate(tab, pruneOpts) || tab === found.currentTab
   );
 
+  function resolveFileSrc(src: string): LogoImageData | undefined {
+    const fileId = FernNavigation.FileId(
+      src.startsWith("file:") ? src.slice(5) : src
+    );
+    const file = docs.definition.filesV2[fileId];
+    if (file == null) {
+      return undefined;
+    }
+
+    if (file.type === "image") {
+      return {
+        src: file.url,
+        width: file.width,
+        height: file.height,
+        blurDataURL: file.blurDataUrl,
+      };
+    } else if (file.type === "url") {
+      return { src: file.url };
+    } else {
+      throw new UnreachableCaseError(file);
+    }
+  }
+
   const content = await withResolvedDocsContent({
     domain: docs.baseUrl.domain,
     found,
@@ -311,6 +336,7 @@ export async function withInitialProps({
         tab: found?.currentTab?.title,
       },
     },
+    replaceSrc: resolveFileSrc,
   });
 
   if (content == null) {
@@ -353,6 +379,19 @@ export async function withInitialProps({
       ? undefined
       : filteredTabs.indexOf(found.currentTab);
 
+  const lightLogoFileId =
+    docs.definition.config.colorsV3?.type === "light"
+      ? docs.definition.config.colorsV3.logo
+      : docs.definition.config.colorsV3?.type === "darkAndLight"
+        ? docs.definition.config.colorsV3.light.logo
+        : undefined;
+  const darkLogoFileId =
+    docs.definition.config.colorsV3?.type === "dark"
+      ? docs.definition.config.colorsV3.logo
+      : docs.definition.config.colorsV3?.type === "darkAndLight"
+        ? docs.definition.config.colorsV3.dark.logo
+        : undefined;
+
   const props: ComponentProps<typeof DocsPage> = {
     baseUrl: docs.baseUrl,
     layout: docs.definition.config.layout,
@@ -361,9 +400,15 @@ export async function withInitialProps({
     colors,
     js: docs.definition.config.js,
     navbarLinks,
-    logoHeight: docs.definition.config.logoHeight,
-    logoHref: logoHref != null ? FernNavigation.Url(logoHref) : undefined,
-    files: docs.definition.filesV2,
+    // logoHeight: docs.definition.config.logoHeight,
+    // logoHref: logoHref != null ? FernNavigation.Url(logoHref) : undefined,
+    logo: {
+      height: docs.definition.config.logoHeight,
+      href: logoHref != null ? FernNavigation.Url(logoHref) : undefined,
+      light:
+        lightLogoFileId != null ? resolveFileSrc(lightLogoFileId) : undefined,
+      dark: darkLogoFileId != null ? resolveFileSrc(darkLogoFileId) : undefined,
+    },
     content,
     announcement:
       docs.definition.config.announcement != null

packages/fern-docs/bundle/src/server/withResolvedDocsContent.ts

@@ -1,8 +1,9 @@
 import { DocsV1Read } from "@fern-api/fdr-sdk";
-import type * as FernNavigation from "@fern-api/fdr-sdk/navigation";
+import * as FernNavigation from "@fern-api/fdr-sdk/navigation";
 import { resolveDocsContent, type DocsContent } from "@fern-docs/ui";
 import { serializeMdx } from "@fern-docs/ui/bundlers/mdx-bundler";
 import { EdgeFlags } from "@fern-docs/utils";
+import { LogoImageData } from "../../../ui/src/atoms/types";
 import { AuthState } from "./auth/getAuthState";
 import { withPrunedNavigation } from "./withPrunedNavigation";
 
@@ -13,6 +14,7 @@ interface WithResolvedDocsContentOpts {
   definition: DocsV1Read.DocsDefinition;
   edgeFlags: EdgeFlags;
   scope?: Record<string, unknown>;
+  replaceSrc?: (src: string) => LogoImageData | undefined;
 }
 
 export async function withResolvedDocsContent({
@@ -22,6 +24,7 @@ export async function withResolvedDocsContent({
   definition,
   edgeFlags,
   scope,
+  replaceSrc,
 }: WithResolvedDocsContentOpts): Promise<DocsContent | undefined> {
   const node = withPrunedNavigation(found.node, {
     visibleNodeIds: [found.node.id],
@@ -67,6 +70,9 @@ export async function withResolvedDocsContent({
     mdxOptions: {
       files: definition.jsFiles,
       scope,
+
+      // inject the file url and dimensions for images and other embeddable files
+      replaceSrc,
     },
     serializeMdx,
     domain,

packages/fern-docs/local-preview-bundle/package.json

@@ -48,6 +48,7 @@
     "react": "^18",
     "react-dom": "^18",
     "styled-jsx": "^5.1.2",
+    "ts-essentials": "^10.0.1",
     "url-join": "5.0.0"
   },
   "devDependencies": {

packages/fern-docs/local-preview-bundle/src/utils/getDocsPageProps.ts

@@ -32,7 +32,9 @@ import {
 import { SidebarTab } from "@fern-platform/fdr-utils";
 import type { GetServerSidePropsResult } from "next";
 import { ComponentProps } from "react";
+import { UnreachableCaseError } from "ts-essentials";
 import urljoin from "url-join";
+import { LogoImageData } from "../../../ui/src/atoms/types";
 
 export async function getDocsPageProps(
   docs: DocsV2Read.LoadDocsForUrlResponse,
@@ -84,6 +86,29 @@ export async function getDocsPageProps(
   // TODO: get feature flags from the API
   const edgeFlags: EdgeFlags = DEFAULT_EDGE_FLAGS;
 
+  function resolveFileSrc(src: string): LogoImageData | undefined {
+    const fileId = FernNavigation.FileId(
+      src.startsWith("file:") ? src.slice(5) : src
+    );
+    const file = docs.definition.filesV2[fileId];
+    if (file == null) {
+      return undefined;
+    }
+
+    if (file.type === "image") {
+      return {
+        src: file.url,
+        width: file.width,
+        height: file.height,
+        blurDataURL: file.blurDataUrl,
+      };
+    } else if (file.type === "url") {
+      return { src: file.url };
+    } else {
+      throw new UnreachableCaseError(file);
+    }
+  }
+
   const content = await resolveDocsContent({
     domain: docs.baseUrl.domain,
     node: node.node,
@@ -109,6 +134,18 @@ export async function getDocsPageProps(
     edgeFlags,
     mdxOptions: {
       files: docs.definition.jsFiles,
+      scope: {
+        env: "development",
+        props: {
+          authed: false,
+          user: undefined,
+          version: node.currentVersion?.versionId,
+          tab: node.currentTab?.title,
+        },
+      },
+
+      // inject the file url and dimensions for images and other embeddable files
+      replaceSrc: resolveFileSrc,
     },
     serializeMdx,
     engine: "next-mdx-remote",
@@ -182,6 +219,19 @@ export async function getDocsPageProps(
     }
   });
 
+  const lightLogoFileId =
+    docs.definition.config.colorsV3?.type === "light"
+      ? docs.definition.config.colorsV3.logo
+      : docs.definition.config.colorsV3?.type === "darkAndLight"
+        ? docs.definition.config.colorsV3.light.logo
+        : undefined;
+  const darkLogoFileId =
+    docs.definition.config.colorsV3?.type === "dark"
+      ? docs.definition.config.colorsV3.logo
+      : docs.definition.config.colorsV3?.type === "darkAndLight"
+        ? docs.definition.config.colorsV3.dark.logo
+        : undefined;
+
   const props: ComponentProps<typeof DocsPage> = {
     baseUrl: docs.baseUrl,
     layout: docs.definition.config.layout,
@@ -190,9 +240,13 @@ export async function getDocsPageProps(
     colors,
     js: docs.definition.config.js,
     navbarLinks,
-    logoHeight: docs.definition.config.logoHeight,
-    logoHref: docs.definition.config.logoHref,
-    files: docs.definition.filesV2,
+    logo: {
+      height: docs.definition.config.logoHeight,
+      href: docs.definition.config.logoHref,
+      light:
+        lightLogoFileId != null ? resolveFileSrc(lightLogoFileId) : undefined,
+      dark: darkLogoFileId != null ? resolveFileSrc(darkLogoFileId) : undefined,
+    },
     content,
     announcement:
       docs.definition.config.announcement != null

packages/fern-docs/mdx/src/mdx-utils/index.ts

@@ -3,5 +3,6 @@ export * from "./is-mdx-element";
 export * from "./is-mdx-expression";
 export * from "./is-mdx-jsx-attr";
 export * from "./markdown-to-string";
+export * from "./mdx-jsx-attribute-to-string";
 export * from "./unknown-to-estree-expression";
 export * from "./unknown-to-mdx-jsx-attr";

packages/fern-docs/mdx/src/mdx-utils/mdx-jsx-attribute-to-string.ts

@@ -0,0 +1,30 @@
+import type { MdxJsxAttribute } from "mdast-util-mdx-jsx";
+
+export function mdxJsxAttributeToString(
+  attribute: MdxJsxAttribute
+): string | undefined {
+  if (typeof attribute.value === "string") {
+    return attribute.value;
+  }
+
+  if (
+    typeof attribute.value === "object" &&
+    attribute.value?.type === "mdxJsxAttributeValueExpression"
+  ) {
+    const expression = attribute.value.value;
+
+    // if expression is wrapped in "" or '', then return the value inside
+    if (expression.startsWith('"') && expression.endsWith('"')) {
+      return expression.slice(1, -1);
+    }
+
+    if (expression.startsWith("'") && expression.endsWith("'")) {
+      return expression.slice(1, -1);
+    }
+
+    // if the expression is wrapped in backticks, we cannot parse it, because it may contain a variable.
+    // for now, we'll just return undefined.
+  }
+
+  return undefined;
+}

packages/fern-docs/ui/src/atoms/docs.ts

@@ -47,9 +47,12 @@ export const EMPTY_DOCS_STATE: DocsProps = {
   layout: undefined,
   js: undefined,
   navbarLinks: [],
-  logoHeight: undefined,
-  logoHref: undefined,
-  files: {},
+  logo: {
+    height: undefined,
+    href: undefined,
+    light: undefined,
+    dark: undefined,
+  },
   content: {
     type: "markdown-page",
     slug: FernNavigation.Slug(""),