add comment

Author: Nicolas Dorseuil

packages/gitbook/src/components/DocumentView/Table/RecordCard.tsx

@@ -165,6 +165,9 @@ export async function RecordCard(
 
     if (target && targetRef) {
         return (
+            // We don't use `Link` directly here because we could end up in a situation where
+            // a link is rendered inside a link, which is not allowed in HTML.
+            // It causes an hydration error in React.
             <LinkBox href={target.href} className={tcls(style, 'hover:before:ring-tint-12/5')}>
                 <LinkOverlay
                     href={target.href}

packages/gitbook/src/components/primitives/Link.tsx

@@ -76,6 +76,10 @@ export const Link = React.forwardRef(function Link(
     );
 });
 
+/**
+ * A box used to contain a link overlay.
+ * It is used to create a clickable area that can contain other elements.
+ */
 export const LinkBox = React.forwardRef(function LinkBox(
     props: React.BaseHTMLAttributes<HTMLDivElement>,
     ref: React.Ref<HTMLDivElement>
@@ -88,6 +92,11 @@ export const LinkBox = React.forwardRef(function LinkBox(
     );
 });
 
+/**
+ * A link overlay that can be used to create a clickable area on top of other elements.
+ * It is used to create a link that covers the entire area of the element without encapsulating it in a link tag.
+ * This is useful to avoid nesting links inside links.
+ */
 export const LinkOverlay = React.forwardRef(function LinkOverlay(
     props: LinkProps,
     ref: React.Ref<HTMLAnchorElement>