Refactor documentation and improve sign-in link relocation logic

Author: srinivaspendem

docs/.vitepress/theme/components/Card.vue

@@ -15,7 +15,12 @@ const props = defineProps({
   cta: String,
 });
 
-const resolvedHref = computed(() => props.link || props.href || "#");
+const hasDestination = computed(() => Boolean((props.link || props.href || "").toString().trim()));
+
+const resolvedHref = computed(() => {
+  const h = (props.link || props.href || "").toString().trim();
+  return h;
+});
 
 // Custom SVG icons for brands
 const customSvgIcons = {
@@ -53,8 +58,9 @@ const IconComponent = computed(() => {
 </script>
 
 <template>
-  <a
-    :href="resolvedHref"
+  <component
+    :is="hasDestination ? 'a' : 'div'"
+    :href="hasDestination ? resolvedHref : undefined"
     class="card-link"
     :class="{ 'card-link--with-cta': cta }"
   >
@@ -72,5 +78,5 @@ const IconComponent = computed(() => {
       <slot />
     </p>
     <span v-if="cta" class="card-cta">{{ cta }} →</span>
-  </a>
+  </component>
 </template>

docs/.vitepress/theme/index.ts

@@ -2,7 +2,7 @@ import type { Theme } from "vitepress";
 import type { ThemeContext } from "@voidzero-dev/vitepress-theme";
 import VoidZeroTheme from "@voidzero-dev/vitepress-theme";
 import { themeContextKey } from "@voidzero-dev/vitepress-theme";
-import { onMounted, watch, nextTick } from "vue";
+import { onMounted, onUnmounted, watch, nextTick } from "vue";
 import { useRoute } from "vitepress";
 import { enhanceAppWithTabs } from "vitepress-plugin-tabs/client";
 import mediumZoom from "medium-zoom";
@@ -93,45 +93,101 @@ function updateHashOnTabClick(event: Event) {
 /**
  * Move "Sign in" CTA to the right utility area (between search and theme toggle).
  * The upstream OSSHeader renders nav links on the left; we remap only this CTA.
+ * Returns true if the link was found and moved (or already in the target region).
  */
-function moveSignInToUtilityArea() {
-  if (typeof document === "undefined") return;
+function moveSignInToUtilityArea(): boolean {
+  if (typeof document === "undefined") return false;
 
   const signInLink = document.querySelector(
-    '.docs-layout header .VPNavBarMenu a.VPLink[href*="sign-in"]',
+    '.docs-layout header a.VPLink[href*="sign-in"]',
   ) as HTMLAnchorElement | null;
-  if (!signInLink) return;
+  if (!signInLink) return false;
+
+  if (signInLink.classList.contains("sign-in-relocated")) {
+    return true;
+  }
 
   const appearanceToggle = document.querySelector(
     ".docs-layout header .VPNavBarAppearance",
   ) as HTMLElement | null;
 
+  if (
+    appearanceToggle?.parentElement &&
+    signInLink.parentElement === appearanceToggle.parentElement
+  ) {
+    signInLink.classList.add("sign-in-relocated");
+    return true;
+  }
+
+  const extraMenu = document.querySelector(
+    ".docs-layout header .VPNavBarExtra",
+  ) as HTMLElement | null;
+  if (extraMenu?.parentElement && signInLink.parentElement === extraMenu.parentElement) {
+    signInLink.classList.add("sign-in-relocated");
+    return true;
+  }
+
   // Desktop (xl+): insert before theme toggle inside the utilities row.
   if (
     appearanceToggle?.parentElement &&
     signInLink.parentElement !== appearanceToggle.parentElement
   ) {
     signInLink.classList.add("sign-in-relocated");
     appearanceToggle.parentElement.insertBefore(signInLink, appearanceToggle);
-    return;
+    return true;
   }
 
   // Tablet fallback (lg-xl): keep it in right controls row before the extra menu.
-  const extraMenu = document.querySelector(
-    ".docs-layout header .VPNavBarExtra",
-  ) as HTMLElement | null;
   if (extraMenu?.parentElement && signInLink.parentElement !== extraMenu.parentElement) {
     signInLink.classList.add("sign-in-relocated");
     extraMenu.parentElement.insertBefore(signInLink, extraMenu);
+    return true;
   }
+
+  return false;
+}
+
+let signInRelocateWarned = false;
+
+function runSignInRelocationWithRetries() {
+  if (typeof document === "undefined" || !document.querySelector(".docs-layout")) {
+    return;
+  }
+
+  const tryOnce = (attempt: number) => {
+    if (moveSignInToUtilityArea()) {
+      return;
+    }
+    if (attempt < 40) {
+      window.setTimeout(() => tryOnce(attempt + 1), 75);
+    } else if (!signInRelocateWarned) {
+      const link = document.querySelector('.docs-layout header a.VPLink[href*="sign-in"]');
+      if (link && !link.classList.contains("sign-in-relocated")) {
+        signInRelocateWarned = true;
+        console.warn(
+          "[plane-docs] Sign-in could not be relocated (header not ready or selectors changed).",
+        );
+      }
+    }
+  };
+
+  tryOnce(0);
+}
+
+function debounce(fn: () => void, ms: number) {
+  let t: ReturnType<typeof setTimeout> | undefined;
+  return () => {
+    if (t) clearTimeout(t);
+    t = setTimeout(fn, ms);
+  };
 }
 
 export default {
   extends: VoidZeroTheme,
   Layout,
   enhanceApp(ctx) {
+    VoidZeroTheme.enhanceApp?.(ctx);
     ctx.app.provide(themeContextKey, planeThemeContext);
-    VoidZeroTheme.enhanceApp(ctx);
     enhanceAppWithTabs(ctx.app);
     ctx.app.component("Card", Card);
     ctx.app.component("CardGroup", CardGroup);
@@ -146,20 +202,59 @@ export default {
       background: "rgba(0, 0, 0, 0.8)",
     });
 
+    let headerObserver: MutationObserver | null = null;
+    let onResize: (() => void) | null = null;
+
     onMounted(() => {
       // Delay tab hash handling to ensure tabs are rendered
       setTimeout(() => {
         handleTabHash();
         setupTabHashUpdates();
-        moveSignInToUtilityArea();
+        runSignInRelocationWithRetries();
+      }, 100);
+
+      const onHeaderMutations = debounce(() => {
+        runSignInRelocationWithRetries();
       }, 100);
 
+      const tryAttachHeaderObserver = () => {
+        if (headerObserver) return;
+        const h = document.querySelector(".docs-layout header");
+        if (!h) return;
+        headerObserver = new MutationObserver(onHeaderMutations);
+        headerObserver.observe(h, { childList: true, subtree: true });
+      };
+      tryAttachHeaderObserver();
+      if (!headerObserver) {
+        const id = window.setInterval(() => {
+          tryAttachHeaderObserver();
+          if (headerObserver) {
+            clearInterval(id);
+          }
+        }, 120);
+        window.setTimeout(() => clearInterval(id), 5000);
+      }
+
+      onResize = debounce(() => {
+        runSignInRelocationWithRetries();
+      }, 150);
+      window.addEventListener("resize", onResize);
+
       // Listen for hash changes
       window.addEventListener("hashchange", () => {
         nextTick(handleTabHash);
       });
     });
 
+    onUnmounted(() => {
+      headerObserver?.disconnect();
+      headerObserver = null;
+      if (onResize) {
+        window.removeEventListener("resize", onResize);
+        onResize = null;
+      }
+    });
+
     // Watch for route changes
     watch(
       () => route.path,
@@ -169,7 +264,7 @@ export default {
           zoom.attach(":not(a) > img:not(.VPImage)");
           handleTabHash();
           setupTabHashUpdates();
-          moveSignInToUtilityArea();
+          runSignInRelocationWithRetries();
         });
       },
     );

docs/.vitepress/theme/style.css

@@ -609,7 +609,7 @@ div[class*="language-"] > span.lang {
   color: #0a0a0a;
 }
 
-.vp-doc .home-feature-cards .card-icon :deep(svg) {
+.vp-doc .home-feature-cards .card-icon svg {
   width: 24px;
   height: 24px;
   flex-shrink: 0;
@@ -746,12 +746,6 @@ div[class*="language-"] > span.lang {
     transform 0.2s ease !important;
 }
 
-/* Prevent first-paint flash in left nav before JS relocates Sign in. */
-.docs-layout header .VPLink[href*="sign-in"]:not(.sign-in-relocated) {
-  opacity: 0 !important;
-  pointer-events: none !important;
-}
-
 .docs-layout header a.VPLink[href*="sign-in"] .vp-external-link-icon {
   display: none !important;
 }

docs/index.md

@@ -8,7 +8,9 @@ description:
 
 <!-- @format -->
 
-# Plane Documentation Plan, track, and ship your work with Plane.
+# Plane documentation
+
+Plan, track, and ship your work with Plane.
 
 This documentation helps you learn Plane, manage projects, collaborate with
 teams, and automate workflows.