Skip to content

Commit

Permalink
fix: frontmatter regression (#1117)
Browse files Browse the repository at this point in the history
  • Loading branch information
@abvthecity
abvthecity authored Jul 8, 2024
1 parent 5886b0c commit 75ca71f
Show file tree
Hide file tree
Showing 6 changed files with 34 additions and 48 deletions.
2 changes: 1 addition & 1 deletion packages/ui/app/src/layout/GuideLayout.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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} />
Expand Down
2 changes: 1 addition & 1 deletion packages/ui/app/src/layout/OverviewLayout.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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} />
Expand Down
11 changes: 6 additions & 5 deletions packages/ui/app/src/mdx/mdx.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand All @@ -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 {
Expand All @@ -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.
Expand Down
45 changes: 15 additions & 30 deletions packages/ui/app/src/mdx/plugins/rehypeLayout.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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":
Expand All @@ -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({
Expand All @@ -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({
Expand All @@ -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({
Expand All @@ -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) {
Expand All @@ -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"],
};
}

Expand Down
16 changes: 8 additions & 8 deletions packages/ui/app/src/resolver/ApiDefinitionResolver.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
},
}),
};
Expand All @@ -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,
},
}),
});
Expand Down
6 changes: 3 additions & 3 deletions packages/ui/app/src/util/convertNavigatableToResolvedPath.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down

0 comments on commit 75ca71f

Please sign in to comment.