Adapt DocCardList for the Teleport docs site (#86)

Partially addresses #29

Swizzle the Docusaurus-native `DocCardList` component and adapt it to
suit the Teleport docs site. Since we prefer a more text-oriented
approach to components, edit `DocCardList` to return a plain `ul`,
rather than tiles.

Since the `DocCardList` component is a Docusaurus-native alternative to
our `remark-toc` plugin, edit `remark-toc` to return a `DocCardList`
instead of querying the filesystem to generate a table of contents. Once
we replace all `(!toc!)` expressions with `<DocCardList />` elements, we
can remove `remark-toc` entirely.

Also make `DocCardList` an MDX component so docs authors don't need to
add `import` statements to the top of a docs page.

To test one function used in `DocCardList`, reorganize unit testing to
use Jest for some frontend code that doesn't depend on React or browser
APIs.
- Rename the Jest config to acknowledge that it's not just for server
  code
- Edit `yarn tests` to run Jest tests for component code.

Author: ptgott

jest.server.config.mjs renamed to jest.config.mjs

@@ -27,7 +27,7 @@
     "storybook:build": "storybook build",
     "storybook:test-ci": "npx concurrently --kill-others --success first --names \"STORYBOOK,TESTS\" -c \"magenta,blue\" \"npx http-server -a 127.0.0.1 --silent storybook-static --port 6006\" \"npx wait-on tcp:127.0.0.1:6006 && yarn storybook:test --url http://127.0.0.1:6006/storybook-static \"",
     "storybook:test": "test-storybook",
-    "test": "NODE_OPTIONS=\"$NODE_OPTIONS --trace-warnings --experimental-vm-modules\" jest --config ./jest.server.config.mjs server/*.test.ts"
+    "test": "NODE_OPTIONS=\"$NODE_OPTIONS --trace-warnings --experimental-vm-modules\" jest --config ./jest.config.mjs server/*.test.ts src/theme/**/*.test.ts"
   },
   "lint-staged": {
     "*.{js,jsx,ts,tsx}": [

package.json

@@ -2,6 +2,4 @@
 
 Here is an intro.
 
-*   [Protect Databases with Teleport](database-access.mdx): Guides to protecting databases with Teleport.
-*   [Protect MySQL with Teleport](mysql.mdx): How to enroll your MySQL database with Teleport
-*   [Protect Postgres with Teleport](postgres.mdx): How to enroll Postgres with your Teleport cluster
+<DocCardList />

server/fixtures/toc/expected.mdx

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "@jest/globals";
 import { Volume, createFsFromVolume } from "memfs";
-import { default as remarkTOC, getTOC } from "../server/remark-toc";
+import { default as remarkTOC } from "../server/remark-toc";
 import { readFileSync } from "fs";
 import { resolve } from "path";
 import { Compatible, VFile, VFileOptions } from "vfile";
@@ -52,104 +52,6 @@ description: "Protecting App 2 with Teleport"
 ---`,
   };
 
-  test("getTOC with one link to a directory", () => {
-    const expected = `- [Application Access](application-access/application-access.mdx): Guides related to Application Access`;
-
-    const vol = Volume.fromJSON({
-      "/docs/docs.mdx": `---
-title: Documentation Home
-description: Guides for setting up the product.
----
-
-Guides for setting up the product.
-
-`,
-      "/docs/application-access/application-access.mdx": `---
-title: "Application Access"
-description: "Guides related to Application Access"
----
-
-`,
-      "/docs/application-access/page1.mdx": `---
-title: "Application Access Page 1"
-description: "Protecting App 1 with Teleport"
----`,
-      "/docs/application-access/page2.mdx": `---
-title: "Application Access Page 2"
-description: "Protecting App 2 with Teleport"
----`,
-    });
-    const fs = createFsFromVolume(vol);
-    const actual = getTOC("/docs/docs.mdx", fs);
-    expect(actual.result).toBe(expected);
-  });
-
-  test("getTOC with multiple links to directories", () => {
-    const expected = `- [Application Access](application-access/application-access.mdx): Guides related to Application Access
-- [Database Access](database-access/database-access.mdx): Guides related to Database Access.`;
-
-    const vol = Volume.fromJSON(testFilesTwoSections);
-    const fs = createFsFromVolume(vol);
-    const actual = getTOC("/docs/docs.mdx", fs);
-    expect(actual.result).toBe(expected);
-  });
-
-  test("getTOC orders sections correctly", () => {
-    const expected = `- [API Usage](api.mdx): Using the API.
-- [Application Access](application-access/application-access.mdx): Guides related to Application Access
-- [Desktop Access](desktop-access/desktop-access.mdx): Guides related to Desktop Access
-- [Initial Setup](initial-setup.mdx): How to set up the product for the first time.
-- [Kubernetes](kubernetes.mdx): A guide related to Kubernetes.`;
-
-    const vol = Volume.fromJSON({
-      "/docs/docs.mdx": `---
-title: Documentation Home
-description: Guides to setting up the product.
----
-
-Guides to setting up the product.
-
-`,
-      "/docs/desktop-access/desktop-access.mdx": `---
-title: "Desktop Access"
-description: "Guides related to Desktop Access"
----
-
-`,
-
-      "/docs/application-access/application-access.mdx": `---
-title: "Application Access"
-description: "Guides related to Application Access"
----
-
-`,
-      "/docs/desktop-access/get-started.mdx": `---
-title: "Get Started"
-description: "Get started with desktop access."
----`,
-      "/docs/application-access/page1.mdx": `---
-title: "Application Access Page 1"
-description: "Protecting App 1 with Teleport"
----`,
-      "/docs/kubernetes.mdx": `---
-title: "Kubernetes"
-description: "A guide related to Kubernetes."
----`,
-
-      "/docs/initial-setup.mdx": `---
-title: "Initial Setup"
-description: "How to set up the product for the first time."
----`,
-      "/docs/api.mdx": `---
-title: "API Usage"
-description: "Using the API."
----`,
-    });
-    const fs = createFsFromVolume(vol);
-    const actual = getTOC("/docs/docs.mdx", fs);
-    expect(actual.result).toBe(expected);
-  });
-
   const transformer = (vfileOptions: VFileOptions) => {
     const file: VFile = new VFile(vfileOptions);
 

server/remark-toc.test.ts

@@ -8,76 +8,6 @@ import type { VFile } from "vfile";
 import type { Root, Content } from "mdast";
 import type { Transformer } from "unified";
 
-// relativePathToFile takes a filepath and returns a path we can use in links
-// to the file in a table of contents page. The link path is a relative path
-// to the directory where we are placing the table of contents page.
-// @param root {string} - the directory path to the table of contents page.
-// @param filepath {string} - the path from which to generate a link path.
-const relativePathToFile = (root: string, filepath: string) => {
-  // Return the filepath without the first segment, removing the first
-  // slash. This is because the TOC file we are generating is located at
-  // root.
-  return filepath.slice(root.length).replace(/^\//, "");
-};
-
-// getTOC generates a list of links to all files in the same directory as
-// filePath except for filePath. The return value is an object with two
-// properties:
-// - result: a string containing the resulting list of links.
-// - error: an error message encountered during processing
-export const getTOC = (filePath: string, fs: any = nodeFS) => {
-  const dirPath = path.dirname(filePath);
-  if (!fs.existsSync(dirPath)) {
-    return {
-      error: `Cannot generate a table of contents for nonexistent directory at ${dirPath}`,
-    };
-  }
-
-  const { name } = path.parse(filePath);
-
-  const files = fs.readdirSync(dirPath, "utf8");
-  let mdxFiles = new Set();
-  const dirs = files.reduce((accum, current) => {
-    // Don't add a TOC entry for the current file.
-    if (name == path.parse(current).name) {
-      return accum;
-    }
-    const stats = fs.statSync(path.join(dirPath, current));
-    if (!stats.isDirectory() && current.endsWith(".mdx")) {
-      mdxFiles.add(path.join(dirPath, current));
-      return accum;
-    }
-    accum.add(path.join(dirPath, current));
-    return accum;
-  }, new Set());
-
-  // Add rows to the menu page for non-menu pages.
-  const entries = [];
-  mdxFiles.forEach((f: string, idx: number) => {
-    const text = fs.readFileSync(f, "utf8");
-    let relPath = relativePathToFile(dirPath, f);
-    const { data } = matter(text);
-    entries.push(`- [${data.title}](${relPath}): ${data.description}`);
-  });
-
-  // Add rows to the menu page for first-level child menu pages
-  dirs.forEach((f: string, idx: number) => {
-    const menuPath = path.join(f, path.parse(f).base + ".mdx");
-    if (!fs.existsSync(menuPath)) {
-      return {
-        error: `there must be a page called ${menuPath} that introduces ${f}`,
-      };
-    }
-    const text = fs.readFileSync(menuPath, "utf8");
-    let relPath = relativePathToFile(dirPath, menuPath);
-    const { data } = matter(text);
-
-    entries.push(`- [${data.title}](${relPath}): ${data.description}`);
-  });
-  entries.sort();
-  return { result: entries.join("\n") };
-};
-
 const tocRegexpPattern = "^\\(!toc!\\)$";
 
 // remarkTOC replaces (!toc!) syntax in a page with a list of docs pages at a
@@ -104,17 +34,17 @@ export default function remarkTOC(): Transformer {
         return;
       }
 
-      const { result, error } = getTOC(vfile.path);
-      if (!!error) {
-        vfile.message(error, node);
-        return;
-      }
-      const tree = fromMarkdown(result, {});
+      const tree = {
+        type: "mdxJsxFlowElement",
+        name: "DocCardList",
+        attributes: [],
+        children: [],
+      };
 
       const grandParent = ancestors[ancestors.length - 2] as Parent;
       const parentIndex = grandParent.children.indexOf(parent);
 
-      grandParent.children.splice(parentIndex, 1, ...(tree as Root).children);
+      grandParent.children.splice(parentIndex, 1, tree);
     });
   };
 }

server/remark-toc.ts

@@ -3,7 +3,6 @@ import type {
   SidebarItemDoc,
   NormalizedSidebarItemCategory,
 } from "@docusaurus/plugin-content-docs/src/sidebars/types.ts";
-import type { PropVersionDoc } from "@docusaurus/plugin-content-docs";
 
 export interface docPage {
   title: string;

server/sidebar-order.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "@jest/globals";
+import { categoryHrefToDocID } from "./href-to-id";
+
+describe("categoryHrefToDocID", () => {
+  interface testCase {
+    description: string;
+    href: string;
+    expectedID: string;
+  }
+
+  const testCases: Array<testCase> = [
+    {
+      description: "category index page in versioned path",
+      href: "/ver/15.x/reference/agent-services/",
+      expectedID: "reference/agent-services/agent-services",
+    },
+    {
+      description: "category index page in unversioned path",
+      href: "/reference/agent-services/",
+      expectedID: "reference/agent-services/agent-services",
+    },
+    {
+      description: "docs URL segment in versioned path",
+      href: "/docs/ver/15.x/admin-guides/access-controls/guides/joining-sessions",
+      expectedID: "admin-guides/access-controls/guides/joining-sessions/joining-sessions",
+    },
+    {
+      description: "docs URL segment in unversioned path",
+      href: "/docs/admin-guides/access-controls/guides/joining-sessions",
+      expectedID: "admin-guides/access-controls/guides/joining-sessions/joining-sessions",
+    },
+  ];
+
+  test.each(testCases)("$description", (c) => {
+    expect(categoryHrefToDocID(c.href)).toEqual(c.expectedID);
+  });
+});

src/theme/DocCardList/href-to-id.test.ts

@@ -0,0 +1,18 @@
+// categoryHrefoToDocID returns the Docusaurus page ID that corresponds to the
+// given href, which points to a category index page. Category pages do not have
+// IDs in the items prop, so we generate a page ID based on the assumption that
+// category page slugs are the same as their containing directory names.
+export function categoryHrefToDocID(href: string): string {
+  // Remove initial path segments that are not involved in generating the page
+  // ID, such as "/docs/" and "/ver/15.x/".
+  let idPrefix = href.replace(new RegExp(`^/(docs/)?(ver/[0-9]+\\.x/)?`), "");
+  // Ensure that trailing slashes are trimmed so we can uniformly add the slug
+  // segment.
+  idPrefix = idPrefix.replace(new RegExp(`/$`), "");
+  const slugRE = new RegExp(`/([^/]+)/?$`);
+  const slug = slugRE.exec(href);
+  if (!slug || slug.length < 2) {
+    throw new Error(`could not identify a category page ID for href ${href}`);
+  }
+  return idPrefix + "/" + slug[1];
+}

src/theme/DocCardList/href-to-id.ts

@@ -0,0 +1,68 @@
+import React from "react";
+import {
+  useCurrentSidebarCategory,
+  filterDocCardListItems,
+  useDocById,
+} from "@docusaurus/plugin-content-docs/client";
+import DocCard from "@theme/DocCard";
+import type { Props } from "@theme/DocCardList";
+import type {
+  PropVersionDoc,
+  PropSidebarItemCategory,
+} from "@docusaurus/plugin-content-docs";
+import { categoryHrefToDocID } from "./href-to-id";
+
+function DocCardListForCurrentSidebarCategory({ className }: Props) {
+  let category: PropSidebarItemCategory;
+  // DocCardList only works if the current page has a sidebar entry, but the
+  // error Docusaurus currently throws is difficult to understand. Throw an
+  // error with a more explicit message.
+  try {
+    category = useCurrentSidebarCategory();
+  } catch ({ message }) {
+    if (!message.includes("Unexpected: cant find current sidebar in context")) {
+      throw new Error(message);
+    }
+    throw new Error(
+      "The current page does not have a corresponding sidebar entry, so it is not possible to use DocCardList. Make sure that the page is represented on the sidebar."
+    );
+  }
+  return <DocCardList items={category.items} className={className} />;
+}
+
+export default function DocCardList(props: Props): JSX.Element {
+  const { items, className } = props;
+  if (!items) {
+    return <DocCardListForCurrentSidebarCategory {...props} />;
+  }
+  const filteredItems = filterDocCardListItems(items).map((item) => {
+    const doc = useDocById(item.docId);
+
+    if (item.type == "link") {
+      return {
+        href: item.href,
+        label: item.label,
+        description: doc?.description,
+      };
+    }
+    if (item.type == "category") {
+      const indexPage = useDocById(categoryHrefToDocID(item.href) ?? undefined);
+
+      return {
+        href: item.href,
+        label: item.label + " (section)",
+        description: indexPage?.description,
+      };
+    }
+  });
+
+  return (
+    <ul className={className}>
+      {filteredItems.map((item, index) => (
+        <li key={index}>
+          <a href={item.href}>{item.label}</a>: {item.description}
+        </li>
+      ))}
+    </ul>
+  );
+}

src/theme/DocCardList/index.tsx

@@ -1,6 +1,7 @@
 import OriginalMDXComponents from "@theme-original/MDXComponents";
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
+import DocCardList from "@theme/DocCardList";
 import Admonition from "@theme/Admonition";
 import React, { type ComponentProps } from "react";
 import Head from "@docusaurus/Head";
@@ -21,6 +22,7 @@ import type { MDXComponentsObject } from "@theme/MDXComponents";
 const MDXComponents: MDXComponentsObject = {
   ...OriginalMDXComponents,
   Details: MDXDetails,
+  DocCardList: DocCardList,
   Head,
   TabItem,
   Tabs,