feat!: add get static props helper function (#691) (#692)

* feat: add get static props helper function (#691)

* refactor: file import (#691)

* Update src/utils/mdx/frontmatter/validateMatter.ts

Co-authored-by: Copilot <[email protected]>

* Update src/utils/mdx/frontmatter/validateMatter.ts

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Fran McDade <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: frano-m

package-lock.json

@@ -76,10 +76,12 @@
     "@tanstack/react-table": "^8.19.2",
     "@tanstack/react-virtual": "^3.13.12",
     "copy-to-clipboard": "3.3.1",
+    "gray-matter": "^4.0.3",
     "isomorphic-dompurify": "^2.22.0",
     "ky": "^1.7.2",
     "next": "^14.2.32",
     "next-auth": "4.24.11",
+    "next-mdx-remote": "^4.4.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-dropzone": "^14.2.3",

package.json

@@ -0,0 +1,13 @@
+import fs from "fs";
+import matter from "gray-matter";
+
+/**
+ * Returns matter object (frontmatter and content) from the given MD/MDX path.
+ * Server-only: uses Node fs, import only in SSG/SSR/build contexts.
+ * @param filePath - File path of MD/MDX file.
+ * @returns matter object.
+ */
+export function getMatter(filePath: string): matter.GrayMatterFile<string> {
+  const markdownWithMeta = fs.readFileSync(filePath, "utf-8");
+  return matter(markdownWithMeta);
+}

src/utils/mdx/frontmatter/getMatter.ts

@@ -0,0 +1,7 @@
+interface BaseFrontmatterProps {
+  description: string;
+  hidden?: boolean;
+  title: string;
+}
+
+export type FrontmatterProps<F extends object> = BaseFrontmatterProps & F;

src/utils/mdx/frontmatter/types.ts

@@ -0,0 +1,20 @@
+import matter from "gray-matter";
+import { FrontmatterProps } from "./types";
+
+/**
+ * Returns the frontmatter from the given gray matter file data.
+ * @param data - Gray matter file data.
+ * @returns Frontmatter.
+ */
+export function validateMatter<F extends object>(
+  data: matter.GrayMatterFile<string>["data"]
+): FrontmatterProps<F> | undefined {
+  if (
+    "title" in data &&
+    typeof data.title === "string" &&
+    "description" in data &&
+    typeof data.description === "string"
+  ) {
+    return data as FrontmatterProps<F>;
+  }
+}

src/utils/mdx/frontmatter/validateMatter.ts

@@ -0,0 +1,62 @@
+import { SerializeOptions } from "next-mdx-remote/dist/types";
+import { serialize } from "next-mdx-remote/serialize";
+import { GetStaticPropsResult } from "next/types";
+import remarkGfm from "remark-gfm";
+import { OutlineItem } from "../../../components/Layout/components/Outline/types";
+import { getMatter } from "../frontmatter/getMatter";
+import { FrontmatterProps } from "../frontmatter/types";
+import { validateMatter } from "../frontmatter/validateMatter";
+import { rehypeSlug } from "../plugins/rehypeSlug";
+import { remarkHeadings } from "../plugins/remarkHeadings";
+import { StaticProps } from "./types";
+
+export async function buildStaticProps<F extends object, P extends object>(
+  fileName: string | undefined,
+  slug: string[] | undefined,
+  frontmatterFn = (
+    frontmatter: FrontmatterProps<F> | undefined
+  ): FrontmatterProps<F> | undefined => frontmatter,
+  serializeOptions: SerializeOptions = {},
+  otherProps: P = {} as P
+): Promise<
+  GetStaticPropsResult<StaticProps<FrontmatterProps<F>, P>> | undefined
+> {
+  if (!slug) return;
+  if (!fileName) return;
+
+  // Extract frontmatter and content from the MDX file.
+  const { content, data } = getMatter(fileName);
+  const frontmatter = frontmatterFn(validateMatter(data));
+
+  // If the frontmatter is hidden, return.
+  if (!frontmatter || frontmatter.hidden) return;
+
+  // We expect the frontmatter to have a title.
+  if (!frontmatter.title) return;
+
+  // Serialize the MDX content.
+  const outline: OutlineItem[] = [];
+  const mdxSource = await serialize(content, {
+    ...serializeOptions,
+    mdxOptions: {
+      development: false,
+      rehypePlugins: [rehypeSlug],
+      remarkPlugins: [[remarkHeadings, { outline }], remarkGfm],
+      ...serializeOptions.mdxOptions,
+    },
+    scope: { ...serializeOptions.scope, frontmatter },
+  });
+
+  const { title: pageTitle } = frontmatter;
+
+  return {
+    props: {
+      frontmatter,
+      mdxSource,
+      outline,
+      pageTitle,
+      slug,
+      ...otherProps,
+    },
+  };
+}

src/utils/mdx/staticGeneration/staticProps.ts

@@ -0,0 +1,16 @@
+import { MDXRemoteSerializeResult } from "next-mdx-remote";
+import { OutlineItem } from "../../../components/Layout/components/Outline/types";
+import { FrontmatterProps } from "../frontmatter/types";
+
+interface BaseStaticProps<F extends object> {
+  frontmatter: FrontmatterProps<F> | null;
+  mdxSource: MDXRemoteSerializeResult | null;
+  outline: OutlineItem[] | null;
+  pageTitle: string;
+  slug: string[];
+}
+
+export type StaticProps<
+  F extends object,
+  P extends object
+> = BaseStaticProps<F> & P;

src/utils/mdx/staticGeneration/types.ts

@@ -0,0 +1,32 @@
+import { GetStaticPropsContext } from "next/types";
+import { resolveRelativeDirs } from "../files/resolveRelativeDirs";
+
+/**
+ * Builds the MDX file path from the given list of doc directories and slug.
+ * @param dirs - Doc directories e.g. ["app", "docs"].
+ * @param slug - Doc slug e.g. ["learn", "featured-analyses"].
+ * @returns MDX file path.
+ */
+export function buildMDXFilePath(
+  dirs: string[],
+  slug: string[] | undefined
+): string | undefined {
+  if (!slug) return;
+  return resolveRelativeDirs(dirs.concat(slug)).concat(".mdx");
+}
+
+/**
+ * Returns the MDX page slug for the given static props context and section.
+ * @param props - Static props context.
+ * @param section - Docs section e.g. "learn".
+ * @returns MDX page slug.
+ */
+export function buildMDXSlug(
+  props: GetStaticPropsContext,
+  section?: string
+): string[] | undefined {
+  const slug = props.params?.slug;
+  if (!slug || typeof slug === "string") return;
+  if (section) return [section, ...slug];
+  return slug;
+}