From 75ca71fa5767b0d4e288cd1526792e3418b6d3fc Mon Sep 17 00:00:00 2001
From: Andrew Jiang <andrew@buildwithfern.com>
Date: Mon, 8 Jul 2024 16:33:09 -0400
Subject: [PATCH] fix: frontmatter regression (#1117)

---
 packages/ui/app/src/layout/GuideLayout.tsx    |  2 +-
 packages/ui/app/src/layout/OverviewLayout.tsx |  2 +-
 packages/ui/app/src/mdx/mdx.ts                | 11 ++---
 .../ui/app/src/mdx/plugins/rehypeLayout.ts    | 45 +++++++------------
 .../app/src/resolver/ApiDefinitionResolver.ts | 16 +++----
 .../util/convertNavigatableToResolvedPath.ts  |  6 +--
 6 files changed, 34 insertions(+), 48 deletions(-)

diff --git a/packages/ui/app/src/layout/GuideLayout.tsx b/packages/ui/app/src/layout/GuideLayout.tsx
index ec70254217..ae8b7cd3b0 100644
--- a/packages/ui/app/src/layout/GuideLayout.tsx
+++ b/packages/ui/app/src/layout/GuideLayout.tsx
@@ -44,7 +44,7 @@ export function GuideLayout({
 }: GuideLayoutProps): ReactElement {
     return (
         <main className="fern-guide-layout">
-            {tableOfContents != null && (
+            {tableOfContents != null && tableOfContents.length > 0 && (
                 <aside className="fern-layout-toc">
                     <FernScrollArea className="px-4 pb-12 pt-8 lg:pr-8">
                         <TableOfContents tableOfContents={tableOfContents} />
diff --git a/packages/ui/app/src/layout/OverviewLayout.tsx b/packages/ui/app/src/layout/OverviewLayout.tsx
index 1369d75c65..7a77158036 100644
--- a/packages/ui/app/src/layout/OverviewLayout.tsx
+++ b/packages/ui/app/src/layout/OverviewLayout.tsx
@@ -40,7 +40,7 @@ export function OverviewLayout({
 }: OverviewLayoutProps): ReactElement {
     return (
         <main className="fern-overview-layout">
-            {tableOfContents != null && (
+            {tableOfContents != null && tableOfContents.length > 0 && (
                 <aside className="fern-layout-toc">
                     <FernScrollArea className="px-4 pb-12 pt-8 lg:pr-8">
                         <TableOfContents tableOfContents={tableOfContents} />
diff --git a/packages/ui/app/src/mdx/mdx.ts b/packages/ui/app/src/mdx/mdx.ts
index 8140a4e864..612508d041 100644
--- a/packages/ui/app/src/mdx/mdx.ts
+++ b/packages/ui/app/src/mdx/mdx.ts
@@ -13,7 +13,7 @@ import { stringHasMarkdown } from "./common/util";
 import { FernDocsFrontmatter } from "./frontmatter";
 import { rehypeFernCode } from "./plugins/rehypeFernCode";
 import { rehypeFernComponents } from "./plugins/rehypeFernComponents";
-import { PageHeaderProps, rehypeFernLayout } from "./plugins/rehypeLayout";
+import { rehypeFernLayout } from "./plugins/rehypeLayout";
 import { rehypeSanitizeJSX } from "./plugins/rehypeSanitizeJSX";
 import { customHeadingHandler } from "./plugins/remarkRehypeHandlers";
 
@@ -24,12 +24,12 @@ type SerializeOptions = NonNullable<Parameters<typeof serialize>[1]>;
 type SerializeMdxOptions = SerializeOptions["mdxOptions"];
 
 export type FernSerializeMdxOptions = SerializeMdxOptions & {
-    pageHeader?: PageHeaderProps;
+    frontmatterOverrides?: FernDocsFrontmatter;
     showError?: boolean;
 };
 
 function withDefaultMdxOptions({
-    pageHeader,
+    frontmatterOverrides,
     showError = process.env.NODE_ENV === "development",
     ...options
 }: FernSerializeMdxOptions = {}): SerializeMdxOptions {
@@ -53,8 +53,9 @@ function withDefaultMdxOptions({
         rehypePlugins.push(...options.rehypePlugins);
     }
 
-    if (pageHeader != null) {
-        rehypePlugins.push([rehypeFernLayout, pageHeader]);
+    // right now, only pages use frontmatterOverrides, so when null, it is implicit that we're serializing a description.
+    if (frontmatterOverrides != null) {
+        rehypePlugins.push([rehypeFernLayout, frontmatterOverrides]);
     }
 
     // Always sanitize JSX at the end.
diff --git a/packages/ui/app/src/mdx/plugins/rehypeLayout.ts b/packages/ui/app/src/mdx/plugins/rehypeLayout.ts
index fd9958bf94..91f15a2562 100644
--- a/packages/ui/app/src/mdx/plugins/rehypeLayout.ts
+++ b/packages/ui/app/src/mdx/plugins/rehypeLayout.ts
@@ -12,26 +12,9 @@ import { FernDocsFrontmatter } from "../frontmatter";
 import { makeToc } from "./makeToc";
 import { wrapChildren } from "./to-estree";
 
-export interface PageHeaderProps {
-    breadcrumbs: string[];
-
-    // the following are defaults, can be overridden by frontmatter
-    title: string;
-    subtitle?: string;
-    editThisPageUrl?: string;
-
-    // the following are overrides that "forces" a config regardless of frontmatter
-    layout?: FernDocsFrontmatter["layout"]; // sometimes we need to force a layout, e.g. reference layout for endpoints
-    hideNavLinks?: boolean;
-
-    // feature flags
-    isTocDefaultEnabled: boolean;
-}
-
-export function rehypeFernLayout(props?: PageHeaderProps): (tree: Root, vfile: VFile) => void {
+export function rehypeFernLayout(matter: FernDocsFrontmatter): (tree: Root, vfile: VFile) => void {
     return async (tree, vfile) => {
-        let matter = vfile.data.matter as FernDocsFrontmatter | undefined;
-        matter = mergePropsWithMatter(props, matter);
+        matter = mergeMatter(vfile.data.matter as FernDocsFrontmatter | undefined, matter);
         vfile.data.matter = matter;
 
         const asideContents = collectAsideContent(tree);
@@ -47,7 +30,7 @@ export function rehypeFernLayout(props?: PageHeaderProps): (tree: Root, vfile: V
 
         const children = tree.children as ElementContent[];
         const subtitle = matter.subtitle != null ? wrapChildren(parseMarkdown(matter.subtitle)) : undefined;
-        const tableOfContents = makeToc(tree, matter["force-toc"]);
+        const tableOfContents = matter["hide-toc"] ? undefined : makeToc(tree, matter["force-toc"]);
         const aside = wrapChildren(asideContents);
         switch (matter.layout) {
             case "custom":
@@ -60,7 +43,7 @@ export function rehypeFernLayout(props?: PageHeaderProps): (tree: Root, vfile: V
                     tableOfContents,
                     children,
                     editThisPageUrl: matter["edit-this-page-url"],
-                    hideFeedback: false,
+                    hideFeedback: matter["hide-feedback"],
                 });
             case "page":
                 return toPageLayoutHastNode({
@@ -70,8 +53,8 @@ export function rehypeFernLayout(props?: PageHeaderProps): (tree: Root, vfile: V
                     tableOfContents,
                     children,
                     editThisPageUrl: matter["edit-this-page-url"],
-                    hideFeedback: false,
-                    hideNavLinks: false,
+                    hideFeedback: matter["hide-feedback"],
+                    hideNavLinks: matter["hide-nav-links"],
                 });
             case "reference":
                 return toReferenceLayoutHastNode({
@@ -81,7 +64,7 @@ export function rehypeFernLayout(props?: PageHeaderProps): (tree: Root, vfile: V
                     children,
                     aside,
                     editThisPageUrl: matter["edit-this-page-url"],
-                    hideFeedback: false,
+                    hideFeedback: matter["hide-feedback"],
                 });
             default:
                 return toGuideLayoutHastNode({
@@ -91,15 +74,15 @@ export function rehypeFernLayout(props?: PageHeaderProps): (tree: Root, vfile: V
                     tableOfContents,
                     children,
                     editThisPageUrl: matter["edit-this-page-url"],
-                    hideFeedback: false,
-                    hideNavLinks: false,
+                    hideFeedback: matter["hide-feedback"],
+                    hideNavLinks: matter["hide-nav-links"],
                 });
         }
     };
 }
 
-function mergePropsWithMatter(
-    props: PageHeaderProps | undefined,
+function mergeMatter(
+    props: FernDocsFrontmatter | undefined,
     matter: FernDocsFrontmatter | undefined,
 ): FernDocsFrontmatter {
     if (matter == null || props == null) {
@@ -109,13 +92,15 @@ function mergePropsWithMatter(
     }
 
     return {
+        ...matter,
+        ...props,
         title: matter.title ?? props.title,
         subtitle: matter.subtitle ?? matter.excerpt ?? props.subtitle,
         "edit-this-page-url": matter["edit-this-page-url"] ?? matter.editThisPageUrl ?? props.editThisPageUrl,
         layout: props.layout ?? matter.layout ?? "guide",
-        "hide-nav-links": props.hideNavLinks ?? matter["hide-nav-links"],
+        "hide-nav-links": props["hide-nav-links"] ?? matter["hide-nav-links"],
         breadcrumbs: matter.breadcrumbs ?? props.breadcrumbs,
-        "force-toc": matter["force-toc"] ?? props.isTocDefaultEnabled,
+        "force-toc": matter["force-toc"] ?? props["force-toc"],
     };
 }
 
diff --git a/packages/ui/app/src/resolver/ApiDefinitionResolver.ts b/packages/ui/app/src/resolver/ApiDefinitionResolver.ts
index 2c98e680c9..d88b09e7f9 100644
--- a/packages/ui/app/src/resolver/ApiDefinitionResolver.ts
+++ b/packages/ui/app/src/resolver/ApiDefinitionResolver.ts
@@ -107,13 +107,13 @@ export class ApiDefinitionResolver {
                             title: page.title,
                             markdown: await serializeMdxWithFrontmatter(pageContent.markdown, {
                                 ...mdxOptions,
-                                pageHeader: {
+                                frontmatterOverrides: {
                                     title: page.title,
                                     breadcrumbs: [], // TODO: implement breadcrumbs
-                                    editThisPageUrl: pageContent.editThisPageUrl,
-                                    hideNavLinks: true,
+                                    "edit-this-page-url": pageContent.editThisPageUrl,
+                                    "hide-nav-links": true,
                                     layout: "reference",
-                                    isTocDefaultEnabled: this.featureFlags.isTocDefaultEnabled,
+                                    "force-toc": this.featureFlags.isTocDefaultEnabled,
                                 },
                             }),
                         };
@@ -133,13 +133,13 @@ export class ApiDefinitionResolver {
                 title: node.title,
                 markdown: await serializeMdxWithFrontmatter(pageContent.markdown, {
                     ...mdxOptions,
-                    pageHeader: {
+                    frontmatterOverrides: {
                         title: node.title,
                         breadcrumbs: [], // TODO: implement breadcrumbs
-                        editThisPageUrl: pageContent.editThisPageUrl,
-                        hideNavLinks: true,
+                        "edit-this-page-url": pageContent.editThisPageUrl,
+                        "hide-nav-links": true,
                         layout: "reference",
-                        isTocDefaultEnabled: this.featureFlags.isTocDefaultEnabled,
+                        "force-toc": this.featureFlags.isTocDefaultEnabled,
                     },
                 }),
             });
diff --git a/packages/ui/app/src/util/convertNavigatableToResolvedPath.ts b/packages/ui/app/src/util/convertNavigatableToResolvedPath.ts
index ef9d80398e..59feb1e380 100644
--- a/packages/ui/app/src/util/convertNavigatableToResolvedPath.ts
+++ b/packages/ui/app/src/util/convertNavigatableToResolvedPath.ts
@@ -152,11 +152,11 @@ export async function convertNavigatableToResolvedPath({
         }
         const serializedMdxContent = await serializeMdxWithFrontmatter(pageContent.markdown, {
             ...mdxOptions,
-            pageHeader: {
+            frontmatterOverrides: {
                 title: node.title,
                 breadcrumbs: found.breadcrumb,
-                editThisPageUrl: pageContent.editThisPageUrl,
-                isTocDefaultEnabled: featureFlags.isTocDefaultEnabled,
+                "edit-this-page-url": pageContent.editThisPageUrl,
+                "force-toc": featureFlags.isTocDefaultEnabled,
             },
         });
         const frontmatter = typeof serializedMdxContent === "string" ? {} : serializedMdxContent.frontmatter;