서버에서 URL로 V1/V2 구분 가능하도록 개선

src/components/gitbook/VersionGate.astro

@@ -1,14 +1,17 @@
 ---
+import { getServerSystemVersion } from "~/state/nav";
+
 import Impl from "./VersionGate";
 
 interface Props {
   default: "v1" | "v2";
 }
 
 const { default: version } = Astro.props;
+const serverSystemVersion = getServerSystemVersion(Astro);
 ---
 
-<Impl client:idle default={version}>
+<Impl client:idle default={version} serverSystemVersion={serverSystemVersion}>
   {Astro.slots.has("v1") ? <slot name="v1" slot="v1" /> : null}
   {Astro.slots.has("v2") ? <slot name="v2" slot="v2" /> : null}
   <slot />

src/components/gitbook/VersionGate.tsx

@@ -2,9 +2,11 @@ import type React from "react";
 
 import { useServerFallback } from "~/misc/useServerFallback";
 import { systemVersionSignal } from "~/state/nav";
+import type { SystemVersion } from "~/type";
 
 interface Props {
-  default?: "v1" | "v2";
+  serverSystemVersion: SystemVersion;
+  default?: SystemVersion;
   v1?: React.ReactNode;
   v2?: React.ReactNode;
   children?: React.ReactNode;
@@ -23,20 +25,22 @@ const isEmptyStaticHtml = (node: React.ReactNode) => {
 };
 
 export default function VersionGate(props: Props) {
-  const systemVersion = useServerFallback(systemVersionSignal.value, "all");
+  const systemVersion = useServerFallback(
+    systemVersionSignal.value,
+    props.serverSystemVersion,
+  );
 
   const hasV1 = !isEmptyStaticHtml(props.v1);
   const hasV2 = !isEmptyStaticHtml(props.v2);
 
-  const v1Content =
-    props.default === "v1" ? (hasV1 ? props.v1 : props.children) : props.v1;
-  const v2Content =
-    props.default === "v2" ? (hasV2 ? props.v2 : props.children) : props.v2;
-
   return (
     <>
-      {systemVersion !== "v1" && v2Content}
-      {systemVersion !== "v2" && v1Content}
+      {
+        {
+          v1: props.default === "v1" && !hasV1 ? props.children : props.v1,
+          v2: props.default === "v2" && !hasV2 ? props.children : props.v2,
+        }[systemVersion]
+      }
     </>
   );
 }

src/layouts/gnb/Dropdown.tsx

@@ -9,15 +9,24 @@ export interface DropdownProps {
   children: React.ReactNode;
   link: string | Record<SystemVersion, string>;
   items: DropdownItem[];
+  serverSystemVersion: SystemVersion;
 }
 export interface DropdownItem {
   label: React.ReactNode;
   link: string;
   systemVersion?: SystemVersion;
 }
-export default function Dropdown({ children, link, items }: DropdownProps) {
+export default function Dropdown({
+  children,
+  link,
+  items,
+  serverSystemVersion,
+}: DropdownProps) {
   const showItemsSignal = useSignal(false);
-  const systemVersion = useServerFallback(systemVersionSignal.value, "all");
+  const systemVersion = useServerFallback(
+    systemVersionSignal.value,
+    serverSystemVersion,
+  );
   return (
     <div
       class="relative h-full inline-flex flex-col cursor-default items-center"

src/layouts/gnb/Gnb.astro

@@ -1,6 +1,7 @@
 ---
 import { clsx } from "clsx";
 
+import { getServerSystemVersion } from "~/state/nav";
 import type { Lang } from "~/type";
 
 import Dropdown from "./Dropdown";
@@ -29,6 +30,7 @@ const en: typeof ko = {
   language: "Language",
 };
 const t = lang === "ko" ? ko : en;
+const serverSystemVersion = getServerSystemVersion(Astro);
 ---
 
 <script>
@@ -51,6 +53,7 @@ const t = lang === "ko" ? ko : en;
 <div class="z-50 h-14">
   <header
     id="gnb"
+    data-selected-system-version={serverSystemVersion}
     class="fixed z-10 h-inherit w-full flex items-center justify-between border-b bg-white"
   >
     <div class="h-full flex flex-grow items-center pl-4 md:pl-6">
@@ -64,7 +67,11 @@ const t = lang === "ko" ? ko : en;
           </div>
         </a>
         <div class="mx-6 md:ml-[70px]">
-          <VersionSwitch url={url.toString()} client:load />
+          <VersionSwitch
+            serverSystemVersion={serverSystemVersion}
+            url={url.toString()}
+            client:load
+          />
         </div>
       </div>
       <div
@@ -78,7 +85,8 @@ const t = lang === "ko" ? ko : en;
       >
         <Dropdown
           client:visible
-          link={{ all: "/api", v1: "/api/rest-v1", v2: "/api/rest-v2" }}
+          serverSystemVersion={serverSystemVersion}
+          link={{ v1: "/api/rest-v1", v2: "/api/rest-v2" }}
           items={[
             { label: "REST API V1", link: "/api/rest-v1", systemVersion: "v1" },
             { label: "REST API V2", link: "/api/rest-v2", systemVersion: "v2" },

src/layouts/gnb/VersionSwitch.tsx

@@ -12,12 +12,21 @@ const hiddenPaths = ["/release-notes", "/blog"];
 export interface VersionSwitchProps {
   url: string;
   className?: string;
+  serverSystemVersion: SystemVersion;
 }
-export function VersionSwitch({ url, className }: VersionSwitchProps) {
+export function VersionSwitch({
+  url,
+  className,
+  serverSystemVersion,
+}: VersionSwitchProps) {
   if (hiddenPaths.some((path) => new URL(url).pathname.startsWith(path)))
     return null;
 
-  const systemVersion = systemVersionSignal.value;
+  const systemVersion = useServerFallback(
+    systemVersionSignal.value,
+    serverSystemVersion,
+  );
+
   return (
     <div
       style={{ transition: "margin 0.1s" }}
@@ -33,15 +42,17 @@ export function VersionSwitch({ url, className }: VersionSwitchProps) {
         className || ""
       }`}
     >
-      <div class={getVersionClass("v1")}>V1</div>
-      <div class={getVersionClass("v2")}>V2</div>
+      <div class={getVersionClass("v1", systemVersion)}>V1</div>
+      <div class={getVersionClass("v2", systemVersion)}>V2</div>
     </div>
   );
 }
 export default VersionSwitch;
 
-function getVersionClass(thisVersion: SystemVersion) {
-  const systemVersion = useServerFallback(systemVersionSignal.value, "all");
+function getVersionClass(
+  thisVersion: SystemVersion,
+  systemVersion: SystemVersion,
+) {
   return `py-4px rounded-[4px] ${
     systemVersion === thisVersion
       ? "bg-orange-500 flex-1 text-white px-12px"

src/layouts/sidebar/DocsNavMenu.astro

@@ -1,5 +1,9 @@
 ---
-import { navOpenStatesSignal, slugSignal } from "~/state/nav";
+import {
+  getServerSystemVersion,
+  navOpenStatesSignal,
+  slugSignal,
+} from "~/state/nav";
 import { calcNavMenuAncestors, navMenu } from "~/state/server-only/nav";
 import type { Lang } from "~/type";
 
@@ -20,6 +24,8 @@ const navOpenStates = (navOpenStatesSignal.value = Object.fromEntries([
   [slug, true],
 ]));
 slugSignal.value = slug;
+
+const serverSystemVersion = getServerSystemVersion(Astro);
 ---
 
 <script>
@@ -65,7 +71,7 @@ slugSignal.value = slug;
     class="relative flex-1 overflow-y-scroll"
     data-slug={slug}
     data-navopenstates={JSON.stringify(navOpenStates)}
-    data-selected-system-version="v1"
+    data-selected-system-version={serverSystemVersion}
   >
     <ul class="flex flex-col gap-1 px-2 pb-4">
       {

src/layouts/sidebar/LeftSidebarItem.tsx

@@ -10,7 +10,14 @@ function LeftSidebarItem(props: NavMenuPage) {
   const pageSlug = slugSignal.value;
   const isActive = pageSlug === slug;
   const href = `/docs${slug}`;
-  return <JustLink title={title} href={href} isActive={isActive} />;
+  return (
+    <JustLink
+      title={title}
+      href={href}
+      isActive={isActive}
+      systemVersion={props.systemVersion}
+    />
+  );
 }
 export default LeftSidebarItem;
 
@@ -25,7 +32,7 @@ function FolderLink({ title, slug, items, systemVersion }: NavMenuPage) {
         class={`flex ${getLinkStyle(isActive)} pr-0`}
         data-active={isActive && "active"} // true로 지정하면 SSR시에는 값 없이 attr key만 들어감
       >
-        <a href={`/docs${slug}`} class="grow">
+        <a href={`/docs${slug}?v=${systemVersion}`} class="grow">
           <LinkTitle title={title} />
         </a>
         <button
@@ -63,7 +70,7 @@ export interface JustLinkProps {
   title: string;
   href: string;
   isActive: boolean;
-  systemVersion?: SystemVersion;
+  systemVersion?: SystemVersion | undefined;
   event?: {
     name: string;
     props: object;
@@ -79,7 +86,7 @@ export function JustLink({
   return (
     <a
       data-system-version={systemVersion}
-      href={href}
+      href={systemVersion ? `${href}?v=${systemVersion}` : href}
       class={getLinkStyle(isActive)}
       data-active={isActive && "active"}
       onClick={() => event && trackEvent(event.name, event.props)}

src/layouts/sidebar/search.tsx

@@ -46,7 +46,7 @@ export const fuseSignal = computed(() => {
   const filteredIndex = searchIndex.filter((item) => {
     const navMenuSystemVersion =
       navMenuSystemVersions[item.slug.replace(/^docs/, "")];
-    if (!navMenuSystemVersion || navMenuSystemVersion === "all") return true;
+    if (!navMenuSystemVersion) return true;
     return navMenuSystemVersion === systemVersion;
   });
   return new Fuse(filteredIndex, { keys: ["title", "description", "text"] });

src/state/nav.ts

@@ -1,4 +1,5 @@
 import { effect, signal } from "@preact/signals";
+import type { AstroGlobal } from "astro";
 
 import type { SystemVersion } from "~/type";
 
@@ -31,11 +32,15 @@ const parseSystemVersion = (value: unknown) => {
 
 export const systemVersionSignal = signal(getInitialSystemVersion());
 function getInitialSystemVersion() {
-  if (isServer) return "all";
+  if (isServer) return "v1"; // default
   const storageItem = globalThis.sessionStorage.getItem("systemVersion");
   const searchParams = new URLSearchParams(location.search);
   return parseSystemVersion(searchParams.get("v") || storageItem);
 }
+export function getServerSystemVersion(astro: AstroGlobal) {
+  const value = astro.url.searchParams.get("v");
+  return parseSystemVersion(value);
+}
 if (isClient) {
   effect(() => {
     const systemVersion = systemVersionSignal.value;

src/state/server-only/nav.ts

@@ -31,13 +31,13 @@ export interface NavMenuPage {
   slug: string;
   title: string;
   items: NavMenuPage[];
-  systemVersion: SystemVersion;
+  systemVersion?: SystemVersion | undefined;
 }
 export interface NavMenuGroup {
   type: "group";
   label: string;
   items: NavMenuPage[];
-  systemVersion: SystemVersion;
+  systemVersion?: SystemVersion | undefined;
 }
 export const navMenuItemsEn = toNavMenuItems(
   navYamlEn as YamlNavMenuToplevelItem[],
@@ -58,7 +58,7 @@ export function calcNavMenuSystemVersions(
   const result: NavMenuSystemVersions = {};
   for (const item of iterNavMenuItems(navMenuItems)) {
     if (!("slug" in item)) continue;
-    result[item.slug] = item.systemVersion;
+    if (item.systemVersion) result[item.slug] = item.systemVersion;
   }
   return result;
 }
@@ -101,7 +101,7 @@ function* iterNavMenuItems(items: NavMenuItem[]): Generator<NavMenuItem> {
 function toNavMenuItems(
   yaml: YamlNavMenuToplevelItem[],
   frontmatters: Frontmatters,
-  systemVersion: SystemVersion = "all",
+  systemVersion?: SystemVersion,
 ): NavMenuItem[] {
   return yaml.map((item) => {
     if (typeof item === "string") {

src/type.ts

@@ -4,7 +4,7 @@ export const isLang = (lang: unknown): lang is Lang => {
   return ["ko", "en"].includes(String(lang));
 };
 
-export type SystemVersion = "all" | "v1" | "v2";
+export type SystemVersion = "v1" | "v2";
 
 export type YamlNavMenuToplevelItem =
   | YamlNavMenuPageSugar