Merge pull request #383 from ghostty-org/fix-sidebar

Ensure Header IDs are unique

Author: mitchellh

src/components/jumplink-header/index.tsx

@@ -11,14 +11,16 @@ interface JumplinkHeaderProps {
   as: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
   className?: string;
   children?: React.ReactNode;
+  "data-index"?: string;
 }
 
 export default function JumplinkHeader({
   className,
   children,
   as,
+  "data-index": dataIndex,
 }: JumplinkHeaderProps) {
-  const id = headerDeeplinkIdentifier(children);
+  const id = headerDeeplinkIdentifier(children, dataIndex);
   const { ref, inView } = useInView({
     // This is our header height!  This also impacts our
     // margin below, but TBH I actually like it needing to
@@ -62,8 +64,14 @@ export default function JumplinkHeader({
 
 /**
  * @param children the MDX children node of the header element
+ * @param dataIndex optional data-index attribute value, which is precomputed and set via
+ *                 our fetch-docs remark parser in the event that this is the 2nd+ time we have
+ *                 encountered this ID, to ensure that the generated ID is unique.
  * @returns The resulting id string which should be applied to the jumplink-header
- */ function headerDeeplinkIdentifier(children?: React.ReactNode): string {
+ */ function headerDeeplinkIdentifier(
+  children?: React.ReactNode,
+  dataIndex?: string,
+): string {
   let flattenedTitle = "";
 
   const extractText = (child: React.ReactNode): void => {
@@ -88,5 +96,10 @@ export default function JumplinkHeader({
 ${JSON.stringify(children, null, 2)}`);
   }
 
+  // Append data-index if it exists
+  if (dataIndex) {
+    flattenedTitle += `-${dataIndex}`;
+  }
+
   return slugify(flattenedTitle, { lower: true });
 }

src/lib/fetch-docs.ts

@@ -149,17 +149,47 @@ function parseAnchorLinks({
       type: string;
       value: string;
     }[];
+    data?: any;
   };
+
   return () => {
+    // We need to keep track of how many times that we have encountered a
+    // given header ID, as to ensure that we don't run into any conflicts.
+    // If there is a conflict, the sidecar will run into issues, and only
+    // the first header will be able to be deep-linked to.
+    //
+    // In the event that we encounter a duplicate Header ID, we'll simply
+    // add a suffix to the ID to make it unique. e.g. if there are two headers
+    // with the same name "Foo", the first ID will be "foo", while the second
+    // will be "foo-2".
+    const encounteredIDs = new Map<string, number>();
+
     return function (node: Node) {
       visit(node, "heading", (node: Node) => {
         if (node.type === "heading") {
           let headingNode = node as HeadingNode;
           if (headingNode.children.length > 0) {
             const text = headingNode.children.map((v) => v.value).join("");
+            const baseId = slugify(text.toLowerCase());
+
+            // If this is not the first occurrence, add a data-index attribute
+            const encounteredCount = (encounteredIDs.get(baseId) || 0) + 1;
+            encounteredIDs.set(baseId, encounteredCount);
+            if (encounteredCount >= 2) {
+              if (!headingNode.data) {
+                headingNode.data = {};
+              }
+              headingNode.data.hProperties = {
+                ...headingNode.data.hProperties,
+                "data-index": encounteredCount.toString(),
+              };
+            }
+            const resolvedID =
+              encounteredCount >= 2 ? `${baseId}-${encounteredCount}` : baseId;
+
             pageHeaders.push({
               depth: headingNode.depth,
-              id: slugify(text.toLowerCase()),
+              id: resolvedID,
               title: text,
             });
           }