feat(cli): Parse logo from frontmatter (#5399)

fern/pages/fern-docs/content/front-matter.mdx

@@ -177,6 +177,28 @@ Controls the conditional rendering of the on-page feedback form at the bottom of
   <img src="./on-page-feedback.png" alt="On-page feedback feature" />
 </Frame>
 
+## Page logo
+
+**Name**: `logo`<br />
+**Type**: object<br />
+**Default**: None
+
+You can override the site-wide logo for a page by setting a field named `logo` in any page's frontmatter like this:
+
+<CodeBlock title='index.mdx logo example'>
+
+```mdx
+---
+logo:
+  light: /path/to/page-logo.png
+  dark: /path/to/page-logo.png
+---
+```
+
+</CodeBlock>
+
+This field specifies the logo for this page. If no logo is set, the site-wide [logo configuration](/learn/docs/getting-started/global-configuration#logo-configuration) is used.
+
 ## SEO metadata
 
 Fern also supports adding SEO-specific metadata in the frontmatter. 

packages/cli/cli/versions.yml

@@ -1,3 +1,29 @@
+- changelogEntry:
+    - summary: |
+        The Fern CLI now supports parsing a `logo` option from your frontmatter. If 
+        you would like to override logo on a specific page you can do so by adding 
+        the following: 
+
+        ```markdown intro.mdx
+        ---
+        logo: /path/to/my/logo
+        ---
+        ```
+
+        or 
+
+        ```markdown intro.mdx
+        ---
+        logo: 
+          light: /path/to/my/light/logo 
+          dark: /path/to/my/dark/logo
+        ---
+        ```
+
+      type: feat
+  irVersion: 53
+  version: 0.46.2
+
 - changelogEntry:
     - summary: |
         Add support for setting the `User-Agent` header value for Go generators.

packages/cli/docs-markdown-utils/package.json

@@ -46,6 +46,7 @@
     "organize-imports-cli": "^0.10.0",
     "prettier": "^2.7.1",
     "typescript": "4.6.4",
-    "vitest": "^2.0.5"
+    "vitest": "^2.0.5",
+    "zod": "^3.22.3"
   }
 }

packages/cli/docs-markdown-utils/src/__test__/parseImagePaths.test.ts

@@ -140,6 +140,90 @@ describe("parseImagePaths", () => {
         );
     });
 
+    it("should parse logo from frontmatter text", () => {
+        const page = '---\nlogo: "path/to/image.png"\n---';
+        const result = parseImagePaths(page, PATHS);
+        expect(result.filepaths).toEqual(["/Volume/git/fern/my/docs/folder/path/to/image.png"]);
+        expect(result.markdown.trim()).toMatchInlineSnapshot(
+            `
+          "---
+          logo:
+            type: fileId
+            value: /Volume/git/fern/my/docs/folder/path/to/image.png
+          ---"
+        `
+        );
+    });
+
+    it("should parse url logo from frontmatter text", () => {
+        const page = '---\nlogo: "https://someurl.com"\n---';
+        const result = parseImagePaths(page, PATHS);
+        expect(result.filepaths).toEqual([]);
+        expect(result.markdown.trim()).toMatchInlineSnapshot(
+            `
+          "---
+          logo:
+            type: url
+            value: 'https://someurl.com'
+          ---"
+        `
+        );
+    });
+
+    it("should parse light and dark logo from frontmatter json", () => {
+        const page = '---\nlogo:\n  light: "path/to/light-image.png"\n  dark: "path/to/dark-image.png"\n---';
+        const result = parseImagePaths(page, PATHS);
+        expect(result.filepaths).toEqual([
+            "/Volume/git/fern/my/docs/folder/path/to/light-image.png",
+            "/Volume/git/fern/my/docs/folder/path/to/dark-image.png"
+        ]);
+        expect(result.markdown.trim()).toMatchInlineSnapshot(
+            `
+          "---
+          logo:
+            light:
+              type: fileId
+              value: /Volume/git/fern/my/docs/folder/path/to/light-image.png
+            dark:
+              type: fileId
+              value: /Volume/git/fern/my/docs/folder/path/to/dark-image.png
+          ---"
+        `
+        );
+    });
+
+    it("should parse light logo from frontmatter json", () => {
+        const page = '---\nlogo:\n  light: "path/to/light-image.png"\n---';
+        const result = parseImagePaths(page, PATHS);
+        expect(result.filepaths).toEqual(["/Volume/git/fern/my/docs/folder/path/to/light-image.png"]);
+        expect(result.markdown.trim()).toMatchInlineSnapshot(
+            `
+          "---
+          logo:
+            light:
+              type: fileId
+              value: /Volume/git/fern/my/docs/folder/path/to/light-image.png
+          ---"
+        `
+        );
+    });
+
+    it("should parse dark logo from frontmatter json", () => {
+        const page = '---\nlogo:\n  dark: "path/to/dark-image.png"\n---';
+        const result = parseImagePaths(page, PATHS);
+        expect(result.filepaths).toEqual(["/Volume/git/fern/my/docs/folder/path/to/dark-image.png"]);
+        expect(result.markdown.trim()).toMatchInlineSnapshot(
+            `
+          "---
+          logo:
+            dark:
+              type: fileId
+              value: /Volume/git/fern/my/docs/folder/path/to/dark-image.png
+          ---"
+        `
+        );
+    });
+
     it("should parse the same result when run twice for frontmatter text", () => {
         const page = '---\nimage: "path/to/image.png"\n---';
         const result = parseImagePaths(page, PATHS);

packages/cli/docs-markdown-utils/src/parseImagePaths.ts

@@ -7,6 +7,7 @@ import { mdxFromMarkdown } from "mdast-util-mdx";
 import { mdx } from "micromark-extension-mdx";
 import { visit } from "unist-util-visit";
 import { parseMarkdownToTree } from "./parseMarkdownToTree";
+import { z } from "zod";
 
 interface AbsolutePathMetadata {
     absolutePathToMdx: AbsoluteFilePath;
@@ -48,6 +49,7 @@ export function parseImagePaths(
     }
 
     visitFrontmatterImages(data, ["image", "og:image", "og:logo", "twitter:image"], mapImage);
+    replaceFrontmatterImagesforLogo(data, mapImage);
 
     const tree = parseMarkdownToTree(content);
 
@@ -206,6 +208,7 @@ export function replaceImagePathsAndUrls(
     }
 
     visitFrontmatterImages(data, ["image", "og:image", "og:logo", "twitter:image"], mapImage);
+    replaceFrontmatterImagesforLogo(data, mapImage);
 
     visit(tree, (node) => {
         if (node.position == null) {
@@ -402,3 +405,49 @@ function visitFrontmatterImages(
         }
     }
 }
+
+const LogoOverrideFrontmatterSchema = z.union([
+    z.string(),
+    z.object({
+        light: z.string().optional(),
+        dark: z.string().optional()
+    })
+]);
+
+export function convertImageToFileIdOrUrl(
+    value: string,
+    mapImage: (image: string | undefined) => string | undefined
+): CjsFdrSdk.docs.latest.FileIdOrUrl {
+    const mappedImage = mapImage(value);
+    return mappedImage
+        ? {
+              type: "fileId",
+              value: CjsFdrSdk.FileId(mappedImage)
+          }
+        : {
+              type: "url",
+              value: CjsFdrSdk.Url(value)
+          };
+}
+
+function replaceFrontmatterImagesforLogo(
+    data: Record<string, any>,
+    mapImage: (image: string | undefined) => string | undefined
+) {
+    const parsedValue = LogoOverrideFrontmatterSchema.safeParse(data.logo);
+    if (!parsedValue.success) {
+        return;
+    }
+    const parsedFrontmatterLogo = parsedValue.data;
+
+    if (typeof parsedFrontmatterLogo === "string") {
+        data.logo = convertImageToFileIdOrUrl(parsedFrontmatterLogo, mapImage);
+    } else {
+        if (parsedFrontmatterLogo.light != null) {
+            data.logo.light = convertImageToFileIdOrUrl(parsedFrontmatterLogo.light, mapImage);
+        }
+        if (parsedFrontmatterLogo.dark != null) {
+            data.logo.dark = convertImageToFileIdOrUrl(parsedFrontmatterLogo.dark, mapImage);
+        }
+    }
+}