feat: add top level "learn" section (#331)

app/components/Docs/components/Content/content.styles.ts

@@ -0,0 +1,27 @@
+import { SectionContent } from "../../../content/content.styles";
+import styled from "@emotion/styled";
+
+// See https://github.com/emotion-js/emotion/issues/1105.
+// See https://github.com/emotion-js/emotion/releases/tag/%40emotion%2Fcache%4011.10.2.
+const ignoreSsrWarning =
+  "/* emotion-disable-server-rendering-unsafe-selector-warning-please-do-not-use-this-the-warning-exists-for-a-reason */";
+export const StyledSectionContent = styled(SectionContent)`
+  margin-top: 0;
+
+  > *:first-child:not(style) ${ignoreSsrWarning} {
+    margin-top: 0;
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    &:hover {
+      a {
+        opacity: 1;
+      }
+    }
+  }
+`;

app/components/Docs/components/SectionOverview/sectionOverview.styles.ts

@@ -0,0 +1,47 @@
+import styled from "@emotion/styled";
+import { bpUpSm } from "@databiosphere/findable-ui/lib/styles/common/mixins/breakpoints";
+import { PALETTE } from "@databiosphere/findable-ui/lib/styles/common/constants/palette";
+
+export const GroupOverview = styled.div`
+  .MuiDivider-root,
+  .MuiTypography-heading {
+    grid-column: 1 / -1;
+  }
+
+  .MuiDivider-root {
+    margin: 32px 0;
+  }
+`;
+
+export const GroupLinks = styled.div`
+  margin-top: 8px;
+
+  ${bpUpSm} {
+    display: grid;
+    gap: 0 64px;
+    grid-auto-columns: 1fr;
+
+    ul + ul {
+      grid-column: 2;
+    }
+  }
+`;
+
+export const StyledUnorderedList = styled("ul")`
+  list-style-position: inside;
+  padding-left: 0 !important;
+
+  li {
+    margin: 4px 0;
+    padding-left: 24px; // required for list-style-position: inside; allows for market to be positioned inside the list item.
+    text-indent: -15px; // required for list-style-position: inside; centering marker; half of the 24px width and half marker width @ 6px.
+
+    > * {
+      margin-left: -6px; // required for list-style-position: inside; assists with vertical alignment of list item; difference between indent and padding adjustments and half of the marker width.
+    }
+
+    &::marker {
+      color: ${PALETTE.PRIMARY_MAIN};
+    }
+  }
+`;

app/components/Docs/components/SectionOverview/sectionOverview.tsx

@@ -0,0 +1,48 @@
+import { Link } from "@databiosphere/findable-ui/lib/components/Links/components/Link/link";
+import { Divider } from "@mui/material";
+import { Fragment } from "react";
+import {
+  GroupOverview,
+  GroupLinks,
+  StyledUnorderedList,
+} from "./sectionOverview.styles";
+import { splitLinks } from "./utils";
+import { Props } from "./types";
+import { TYPOGRAPHY_PROPS } from "@databiosphere/findable-ui/lib/styles/common/mui/typography";
+import { Heading } from "../common/Typography/Heading/heading";
+
+export const SectionOverview = ({ overview }: Props): JSX.Element | null => {
+  if (!overview) return null;
+  return (
+    <Fragment>
+      {overview.map(({ label, links }, groupIndex) => {
+        return (
+          links.length > 0 && (
+            <GroupOverview key={groupIndex}>
+              {groupIndex > 0 && <Divider />}
+              <Heading
+                component="h2"
+                headingValue={label}
+                variant={TYPOGRAPHY_PROPS.VARIANT.HEADING}
+              />
+              <GroupLinks>
+                {splitLinks(links).map(
+                  (links, linksIndex) =>
+                    links.length > 0 && (
+                      <StyledUnorderedList key={linksIndex}>
+                        {links.map((linkProps, listIndex) => (
+                          <li key={listIndex}>
+                            <Link {...linkProps} />
+                          </li>
+                        ))}
+                      </StyledUnorderedList>
+                    )
+                )}
+              </GroupLinks>
+            </GroupOverview>
+          )
+        );
+      })}
+    </Fragment>
+  );
+};

app/components/Docs/components/SectionOverview/types.ts

@@ -0,0 +1,10 @@
+import { LinkProps } from "@databiosphere/findable-ui/lib/components/Links/components/Link/link";
+
+export interface Overview {
+  label: string;
+  links: LinkProps[];
+}
+
+export interface Props {
+  overview?: Overview[];
+}

app/components/Docs/components/SectionOverview/utils.ts

@@ -0,0 +1,13 @@
+import { LinkProps } from "@databiosphere/findable-ui/lib/components/Links/components/Link/link";
+
+const MAX_ROWS = 3;
+
+/**
+ * Splits group overview links into two arrays suitable for a two-column layout.
+ * @param links - Section overview links.
+ * @returns section overview links, evenly split into two arrays.
+ */
+export function splitLinks(links: LinkProps[]): LinkProps[][] {
+  const sliceIndex = Math.max(MAX_ROWS, Math.ceil(links.length / 2));
+  return [links.slice(0, sliceIndex), links.slice(sliceIndex)];
+}

app/components/Docs/components/common/Typography/Heading/heading.tsx

@@ -0,0 +1,34 @@
+import { AnchorLink } from "@databiosphere/findable-ui/lib/components/common/AnchorLink/anchorLink";
+import { Typography, TypographyProps } from "@mui/material";
+import { TYPOGRAPHY_PROPS } from "@databiosphere/findable-ui/lib/styles/common/mui/typography";
+import { slugifyHeading } from "../../../../../../../plugins/utils";
+
+export interface HeadingProps {
+  component?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+  enableAnchor?: boolean;
+  headingValue: string;
+  headingValueSlug?: string;
+  sx?: TypographyProps["sx"];
+  variant?: TypographyProps["variant"];
+}
+
+export const Heading = ({
+  component = "h1",
+  enableAnchor = true,
+  headingValue,
+  headingValueSlug = slugifyHeading(headingValue),
+  sx = { mb: 2 },
+  variant = TYPOGRAPHY_PROPS.VARIANT.HEADING_LARGE,
+}: HeadingProps): JSX.Element => {
+  return (
+    <Typography
+      component={component}
+      id={headingValueSlug}
+      sx={{ ...sx, position: "relative" }}
+      variant={variant}
+    >
+      {headingValue}
+      {enableAnchor && <AnchorLink anchorLink={headingValueSlug} />}
+    </Typography>
+  );
+};

app/docs/common/files/utils.ts

@@ -0,0 +1,57 @@
+import fs from "fs";
+import * as path from "path";
+
+/**
+ * Returns true if the file is an MDX file.
+ * @param fileName - File name.
+ * @returns true if the file is an MDX file.
+ */
+function isMdxFile(fileName: string): boolean {
+  return fileName.endsWith(".mdx");
+}
+
+/**
+ * Maps each MDX file path to its slug.
+ * @param docsDirectory - Docs directory.
+ * @param dirPath - Directory path.
+ * @param slugByFilePaths - Accumulator: Map of slug by mdx file path.
+ * @returns returns slug by mdx file path.
+ */
+export function mapSlugByFilePaths(
+  docsDirectory: string,
+  dirPath = docsDirectory,
+  slugByFilePaths: Map<string, string[]> = new Map()
+): Map<string, string[]> {
+  const dirents = fs.readdirSync(dirPath, { withFileTypes: true });
+  return dirents.reduce((acc, dirent) => {
+    /* Accumulate the slug for each MDX file. */
+    if (dirent.isFile() && isMdxFile(dirent.name)) {
+      const mdxPath = path.resolve(dirPath, dirent.name);
+      /* Build the slug from the file relative directory and file name. */
+      const mdxRelativePath = path.relative(docsDirectory, mdxPath);
+      const { dir, name } = path.parse(mdxRelativePath);
+      let slug = [] as string[];
+      if (dir) slug = dir.split(path.sep);
+      slug.push(name);
+      acc.set(mdxPath, slug);
+    }
+    /* Recurse into subdirectories. */
+    if (dirent.isDirectory()) {
+      mapSlugByFilePaths(
+        docsDirectory,
+        path.resolve(dirPath, dirent.name),
+        acc
+      );
+    }
+    return acc;
+  }, slugByFilePaths);
+}
+
+/**
+ * Resolves the relative path to an absolute path for the docs directory.
+ * @param relativePath - Relative paths.
+ * @returns absolute path.
+ */
+export function resolveRelativePath(relativePath: string[]): string {
+  return path.join(process.cwd(), "app", "docs", ...relativePath);
+}

app/docs/common/frontmatter/types.ts

@@ -0,0 +1,27 @@
+import { Breadcrumb } from "@databiosphere/findable-ui/lib/components/common/Breadcrumbs/breadcrumbs";
+import { OutlineItem } from "@databiosphere/findable-ui/lib/components/Layout/components/Outline/types";
+import { Overview } from "../../../components/Docs/components/SectionOverview/types";
+
+export type Frontmatter = FrontmatterBase &
+  FrontmatterBreadcrumb &
+  FrontmatterOutline;
+
+interface FrontmatterBase {
+  description: string;
+  hidden?: boolean;
+  subtitle?: string;
+  title: string;
+}
+
+interface FrontmatterBreadcrumb {
+  breadcrumbs?: Breadcrumb[];
+}
+
+export interface FrontmatterOutline {
+  enableOutline?: boolean;
+  outline?: OutlineItem[];
+}
+
+export interface FrontmatterOverview {
+  overview?: Overview[];
+}

app/docs/common/frontmatter/utils.ts

@@ -0,0 +1,30 @@
+import fs from "fs";
+import matter from "gray-matter";
+import { Frontmatter } from "./types";
+
+/**
+ * Returns matter object (frontmatter and content) from the given MDX path.
+ * @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);
+}
+
+/**
+ * Returns the frontmatter from the given grey matter file data.
+ * @param data - Grey matter file data.
+ * @returns frontmatter.
+ */
+export function sanitizeFrontmatter(
+  data: matter.GrayMatterFile<string>["data"]
+): Frontmatter | undefined {
+  if ("title" in data) {
+    const { enableOutline = true } = data;
+    return {
+      enableOutline,
+      ...data,
+    } as Frontmatter;
+  }
+}

app/docs/common/mdx/constants.ts

@@ -0,0 +1,8 @@
+import { MDXComponents } from "mdx/types";
+import { AnchorLink } from "@databiosphere/findable-ui/lib/components/common/AnchorLink/anchorLink";
+import { SectionOverview } from "../../../components/Docs/components/SectionOverview/sectionOverview";
+
+export const MDX_COMPONENTS: MDXComponents = {
+  AnchorLink,
+  SectionOverview,
+};

app/docs/common/staticGeneration/staticPaths.ts

@@ -0,0 +1,16 @@
+import { GetStaticPathsResult } from "next/types";
+import { mapSlugByFilePaths, resolveRelativePath } from "../files/utils";
+
+/**
+ * Generates static paths for the docs site, for the specified relative paths.
+ * @param relativePaths - Relative paths.
+ * @returns static paths.
+ */
+export function buildStaticPaths(
+  relativePaths: string[]
+): GetStaticPathsResult["paths"] {
+  const slugByFilePaths = mapSlugByFilePaths(
+    resolveRelativePath(relativePaths)
+  );
+  return [...slugByFilePaths].map(([, slug]) => ({ params: { slug } }));
+}

app/docs/common/staticGeneration/staticProps.ts

@@ -0,0 +1,60 @@
+import { OutlineItem } from "@databiosphere/findable-ui/lib/components/Layout/components/Outline/types";
+import { serialize } from "next-mdx-remote/serialize";
+import { GetStaticPropsResult } from "next/types";
+import remarkGfm from "remark-gfm";
+import { Frontmatter } from "../frontmatter/types";
+import { StaticProps } from "./types";
+import { getMatter, sanitizeFrontmatter } from "../frontmatter/utils";
+import { rehypeSlug } from "../../../../plugins/rehypeSlug";
+import { remarkHeadings } from "../../../../plugins/remarkHeadings";
+import { SerializeOptions } from "next-mdx-remote/dist/types";
+import { resolveRelativePath } from "../files/utils";
+
+export async function buildStaticProps(
+  slug: string[] | undefined,
+  frontmatterFn = (
+    frontmatter: Frontmatter | undefined
+  ): Frontmatter | undefined => frontmatter,
+  serializeOptions: SerializeOptions = {}
+): Promise<GetStaticPropsResult<StaticProps> | undefined> {
+  if (!slug) return;
+
+  // Build the file name from the slug.
+  const fileName = slug.join("/").concat(".mdx");
+
+  // Extract frontmatter and content from the MDX file.
+  const { content, data } = getMatter(resolveRelativePath([fileName]));
+  const frontmatter = frontmatterFn(sanitizeFrontmatter(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],
+    },
+    scope: { ...serializeOptions.scope, frontmatter },
+  });
+
+  const { title: pageTitle } = frontmatter;
+
+  return {
+    props: {
+      frontmatter,
+      mdxSource,
+      pageTitle,
+      slug,
+      themeOptions: {
+        palette: { background: { default: "#FAFBFB" } }, // SMOKE_LIGHTEST
+      },
+    },
+  };
+}