feat: Optional frontmatter logo for page

fern/apis/fdr/definition/docs/latest/frontmatter.yml

@@ -35,6 +35,9 @@ types:
         docs: |
           The subtitle of the page. This is a markdown string that is rendered below the title.
           If `description` is not set, this will be used for the <meta name="description"> tag in the HTML.
+      logo:
+        type: optional<Logo>
+        docs: The logo for this page.
       image:
         type: optional<commons.FileIdOrUrl>
         docs: The URL to this page's image. This is currently an alias for `og:image`, but its purpose may change to a be a cover-image (pre-title).
@@ -67,6 +70,21 @@ types:
         type: optional<string>
         docs: The canonical URL of the page. This is used for the <link rel="canonical"> tag in the HTML.
 
+  Logo:
+    discriminated: false
+    union:
+      - commons.FileIdOrUrl
+      - LogoConfiguration
+
+  LogoConfiguration:
+    properties:
+      light:
+        type: optional<commons.FileIdOrUrl>
+        docs: The URL to this page's light theme logo.
+      dark:
+        type: optional<commons.FileIdOrUrl>
+        docs: The URL to this page's dark theme logo.
+
   Layout:
     enum:
       - value: guide

packages/fdr-sdk/src/docs/frontmatter.ts

@@ -37,4 +37,5 @@ export const EMPTY_FRONTMATTER: Frontmatter = {
     nofollow: undefined,
     "jsonld:breadcrumb": undefined,
     keywords: undefined,
+    logo: undefined,
 };

packages/ui/app/src/atoms/docs.ts

@@ -62,6 +62,7 @@ export const EMPTY_DOCS_STATE: DocsProps = {
         hasAside: false,
         apis: {},
         endpointIdsToSlugs: {},
+        frontmatter: undefined,
     },
     featureFlags: DEFAULT_FEATURE_FLAGS,
     apis: [],
@@ -73,6 +74,7 @@ export const EMPTY_DOCS_STATE: DocsProps = {
     user: undefined,
     defaultLang: "curl",
     stylesheet: "",
+    frontmatterLogoOverride: undefined,
 };
 
 export const DOCS_ATOM = atomWithReducer<DocsProps, DocsProps>(EMPTY_DOCS_STATE, (_, next) => {

packages/ui/app/src/atoms/files.ts

@@ -1,4 +1,4 @@
-import type { DocsV1Read } from "@fern-api/fdr-sdk/client/types";
+import { DocsV1Read } from "@fern-api/fdr-sdk/client/types";
 import { isEqual } from "es-toolkit/predicate";
 import { atom, useAtomValue } from "jotai";
 import { selectAtom } from "jotai/utils";
@@ -9,5 +9,13 @@ export const FILES_ATOM = selectAtom(DOCS_ATOM, (docs) => docs.files, isEqual);
 FILES_ATOM.debugLabel = "FILES_ATOM";
 
 export function useFile(fileId: DocsV1Read.FileId): DocsV1Read.File_ | undefined {
-    return useAtomValue(useMemoOne(() => atom((get) => get(FILES_ATOM)[fileId]), [fileId]));
+    return useAtomValue(
+        useMemoOne(
+            () =>
+                atom(
+                    (get) => get(FILES_ATOM)[DocsV1Read.FileId(fileId.startsWith("file:") ? fileId.slice(5) : fileId)],
+                ),
+            [fileId],
+        ),
+    );
 }

packages/ui/app/src/atoms/logo.ts

@@ -1,3 +1,4 @@
+import { FileIdOrUrl, Logo, LogoConfiguration } from "@fern-api/fdr-sdk/docs";
 import { atom, useAtomValue } from "jotai";
 import { DOCS_ATOM } from "./docs";
 import { FEATURE_FLAGS_ATOM } from "./flags";
@@ -17,3 +18,37 @@
 export function useLogoHeight(): number {
     return useAtomValue(LOGO_HEIGHT_ATOM);
 }
+
+function isFileIdOrUrl(logo: Logo | undefined): logo is FileIdOrUrl {
+    if (logo == null) {
+        return false;
+    }
+    if (typeof logo !== "object") {
+        return false;
+    }
+    if (!("type" in logo && "value" in logo)) {
+        return false;
+    }
+    return logo.type === "fileId" || logo.type === "url";
+}
+
+export const LOGO_OVERRIDE_ATOM = atom<LogoConfiguration | undefined>((get) => {
+    const logo = get(DOCS_ATOM).frontmatterLogoOverride ?? undefined;
+    console.log("frontmatter logo", logo);
+
+    if (logo != null && typeof logo === "object") {
+        if ("light" in logo && "dark" in logo && isFileIdOrUrl(logo.light) && isFileIdOrUrl(logo.dark)) {
+            return { light: logo.light, dark: logo.dark };
+        }
+        if ("light" in logo && isFileIdOrUrl(logo.light)) {
+            return { light: logo.light, dark: logo.light };
+        }
+        if ("dark" in logo && isFileIdOrUrl(logo.dark)) {
+            return { light: logo.dark, dark: logo.dark };
+        }
+        if (isFileIdOrUrl(logo)) {
+            return { light: logo, dark: logo };
+        }
+    }
+    return undefined;
+});

packages/ui/app/src/atoms/types.ts

@@ -55,6 +55,7 @@ export interface DocsProps {
     navbarLinks: NavbarLink[];
     logoHeight: DocsV1Read.Height | undefined;
     logoHref: DocsV1Read.Url | undefined;
+    frontmatterLogoOverride: FernDocs.Frontmatter["logo"] | undefined;
     files: Record<DocsV1Read.FileId, DocsV1Read.File_>;
     content: DocsContent;
     featureFlags: FeatureFlags;

packages/ui/app/src/header/HeaderLogoImage.tsx

@@ -1,7 +1,7 @@
 import { DocsV1Read } from "@fern-api/fdr-sdk";
 import { useAtomValue } from "jotai";
 import { ReactElement } from "react";
-import { DOCS_ATOM, useColors, useFile, useLogoHeight } from "../atoms";
+import { DOCS_ATOM, LOGO_OVERRIDE_ATOM, useColors, useFile, useLogoHeight } from "../atoms";
 import { FernImage } from "../components/FernImage";
 
 function FernFileImage({
@@ -11,12 +11,56 @@
     return <FernImage src={useFile(fileId)} {...props} />;
 }
 
+function FernFileOrUrlImage({
+    fileIdOrUrl,
+    ...props
+}: Omit<FernImage.Props, "src"> & { fileIdOrUrl: DocsV1Read.FileIdOrUrl }): ReactElement {
+    if (fileIdOrUrl.type === "fileId") {
+        return <FernFileImage fileId={fileIdOrUrl.value} {...props} />;
+    }
+    return <FernImage src={{ type: "url", url: fileIdOrUrl.value }} {...props} />;
+}
+
 export function HeaderLogoImage(): ReactElement | null {
     const colors = useColors();
     const logoImageHeight = useLogoHeight();
     const title = useAtomValue(DOCS_ATOM).title ?? "Logo";
+    const logoConfiguration = useAtomValue(LOGO_OVERRIDE_ATOM);
+    console.log("logoConfiguration", logoConfiguration);
 
-    if (colors.dark != null && colors.light != null) {
+    if (logoConfiguration != null) {
+        const lightLogo = logoConfiguration.light;
+        const darkLogo = logoConfiguration.dark;
+
+        return (
+            <>
+                {lightLogo != null && (
+                    <FernFileOrUrlImage
+                        alt={title}
+                        fileIdOrUrl={lightLogo}
+                        className="fern-logo-light"
+                        height={logoImageHeight}
+                        style={{ height: logoImageHeight }}
+                        priority={true}
+                        loading="eager"
+                        quality={100}
+                    />
+                )}
+                {darkLogo != null && (
+                    <FernFileOrUrlImage
+                        alt={title}
+                        fileIdOrUrl={darkLogo}
+                        className="fern-logo-dark"
+                        height={logoImageHeight}
+                        style={{ height: logoImageHeight }}
+                        priority={true}
+                        loading="eager"
+                        quality={100}
+                    />
+                )}
+            </>
+        );
+    } else if (colors.dark != null && colors.light != null) {
         return (
             <>
                 {colors.light.logo != null && (

packages/ui/app/src/resolver/DocsContent.ts

@@ -52,6 +52,7 @@ export declare namespace DocsContent {
          * The Request / Response snippets will use this to link back to the endpoint reference page.
          */
         endpointIdsToSlugs: Record<FernNavigation.EndpointId, FernNavigation.Slug>;
+        frontmatter: FernDocs.Frontmatter | undefined;
     }
 
     interface ApiEndpointPage {

packages/ui/app/src/resolver/resolveMarkdownPage.ts

@@ -161,5 +161,6 @@ export async function resolveMarkdownPageWithoutApiRefs({
         breadcrumb,
         neighbors,
         hasAside,
+        frontmatter,
     };
 }

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

@@ -341,6 +341,7 @@ export async function withInitialProps({
             docs.definition.filesV2,
             found.tabs.length > 0,
         ),
+        frontmatterLogoOverride: content?.type === "markdown-page" ? content.frontmatter?.logo : undefined,
     };
 
     // if the user specifies a github navbar link, grab the repo info from it and save it as an SWR fallback