HBASE-29878 Improve the Documentation UI

hbase-website/.gitignore

@@ -18,6 +18,9 @@
 /build/
 .vite
 
+# Fumadocs
+.source/
+
 # Logs
 logs
 *.log
@@ -32,5 +35,15 @@ lerna-debug.log*
 /node/
 
 # Generated files
-/app/pages/team/developers.json
+/app/pages/_landing/team/developers.json
+/app/pages/_docs/docs/_mdx/(multi-page)/configuration/hbase-default.md
+/app/lib/export-pdf/hbase-version.json
+/public/books/**
 
+# Playwright
+node_modules/
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+/playwright/.auth/

hbase-website/app/app.css

@@ -18,9 +18,11 @@
 
 @import "tailwindcss";
 @import "tw-animate-css";
-@import "highlight.js/styles/github.css";
+@import "fumadocs-ui/css/shadcn.css";
+@import "fumadocs-ui/css/preset.css";
 
-@theme {
+@plugin "@tailwindcss/typography" {
+  className: prose-original;
 }
 
 @custom-variant dark (&:is(.dark *));
@@ -169,6 +171,10 @@
     font-family: "Inter", sans-serif;
     font-synthesis: none;
   }
+
+  .print-only {
+    display: none;
+  }
 }
 
 @layer utilities {
@@ -179,33 +185,103 @@
   }
 }
 
-/* Code syntax highlighting for dark mode */
-.dark pre code.hljs {
-  background: oklch(0.2 0 0);
-  color: oklch(0.85 0 0);
-}
+/* For rendering a PDF */
+@media print {
+  @page {
+    size: A4;
+  }
 
-.dark .hljs-comment {
-  color: oklch(0.55 0 0);
-}
+  /* Utility classes */
+  .print-only {
+    display: block !important;
+  }
+  .no-print {
+    display: none !important;
+  }
 
-.dark .hljs-keyword {
-  color: oklch(0.75 0.12 340);
-}
+  /* Hide layout elements */
+  #nd-docs-layout {
+    --fd-sidebar-width: 0px !important;
+  }
+  #nd-sidebar {
+    display: none;
+  }
+  header {
+    display: none !important;
+  }
+  /* Hide copy button in the code blocks */
+  figure > div > button {
+    display: none !important;
+  }
 
-.dark .hljs-string {
-  color: oklch(0.75 0.1 140);
-}
+  /* Every major section starts on a new page */
+  h1:not(:first-of-type) {
+    break-before: page;
+    margin-top: 0; /* Remove top margin since it's at the top of a page now */
+  }
 
-.dark .hljs-number {
-  color: oklch(0.75 0.1 100);
-}
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    break-after: avoid;
+    break-inside: avoid;
+  }
 
-.dark .hljs-title {
-  color: oklch(0.75 0.12 260);
-}
+  /* Hides the <hr> line */
+  hr {
+    display: none;
+  }
+
+  /* Force tables to wrap the content */
+  table {
+    max-width: 100%;
+    table-layout: fixed;
+    word-wrap: break-word;
+  }
+  th,
+  td {
+    padding: 6px 10px !important;
+    word-break: break-all; /* Older browsers */
+    overflow-wrap: anywhere; /* Modern browsers: breaks at any character */
+    hyphens: auto; /* Adds a hyphen if the language is defined */
+  }
+  thead {
+    display: table-header-group; /* Re-renders header on every new page */
+  }
+  /* Don't split a row on two pages, just move it to the next page */
+  tr {
+    break-inside: avoid;
+  }
+
+  /* Force code blocks to wrap instead of scroll */
+  pre,
+  code {
+    max-width: 100% !important;
+    white-space: pre-wrap !important;
+    word-break: break-all !important;
+    overflow-wrap: break-word !important;
+  }
 
-.dark .hljs-name,
-.dark .hljs-attribute {
-  color: oklch(0.7 0.12 200);
+  /* Targets Code and Tables */
+  pre,
+  table,
+  blockquote {
+    /* Try to keep it on one page if possible */
+    break-inside: auto;
+    /* If it breaks, ensure at least 3 lines stay on the current page */
+    orphans: 3;
+    /* If it breaks, ensure at least 3 lines move to the next page */
+    widows: 3;
+  }
+
+  /* Remove the height restriction and scrolling from the code blocks */
+  figure .fd-scroll-container.max-h-\[600px\] {
+    max-height: none !important;
+    overflow: visible !important;
+    height: auto !important;
+    display: block !important;
+  }
 }

hbase-website/app/components/docs/layout/docs/client.tsx

@@ -0,0 +1,157 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+import {
+  type ComponentProps,
+  createContext,
+  type ReactNode,
+  use,
+  useEffect,
+  useMemo,
+  useState
+} from "react";
+import { useSidebar } from "../sidebar/base";
+import { usePathname } from "fumadocs-core/framework";
+import Link from "fumadocs-core/link";
+import type { SidebarTab } from "../sidebar/tabs";
+import { isTabActive } from "../sidebar/tabs/dropdown";
+import { cn } from "@/lib/utils";
+
+export const LayoutContext = createContext<{
+  isNavTransparent: boolean;
+} | null>(null);
+
+export function LayoutContextProvider({
+  navTransparentMode = "none",
+  children
+}: {
+  navTransparentMode?: "always" | "top" | "none";
+  children: ReactNode;
+}) {
+  const isTop = useIsScrollTop({ enabled: navTransparentMode === "top" }) ?? true;
+  const isNavTransparent = navTransparentMode === "top" ? isTop : navTransparentMode === "always";
+
+  return (
+    <LayoutContext
+      value={useMemo(
+        () => ({
+          isNavTransparent
+        }),
+        [isNavTransparent]
+      )}
+    >
+      {children}
+    </LayoutContext>
+  );
+}
+
+export function LayoutHeader(props: ComponentProps<"header">) {
+  const { isNavTransparent } = use(LayoutContext)!;
+
+  return (
+    <header data-transparent={isNavTransparent} {...props}>
+      {props.children}
+    </header>
+  );
+}
+
+export function LayoutBody({ className, style, children, ...props }: ComponentProps<"div">) {
+  const { collapsed } = useSidebar();
+
+  return (
+    <div
+      id="nd-docs-layout"
+      className={cn(
+        "grid min-h-(--fd-docs-height) auto-cols-auto auto-rows-auto overflow-x-clip transition-[grid-template-columns] [--fd-docs-height:100dvh] [--fd-header-height:0px] [--fd-sidebar-width:0px] [--fd-toc-popover-height:0px] [--fd-toc-width:285px] max-xl:[--fd-toc-popover-height:--spacing(10)] max-md:[--fd-header-height:--spacing(14)] md:[--fd-sidebar-width:285px]",
+        className
+      )}
+      data-sidebar-collapsed={collapsed}
+      style={
+        {
+          gridTemplate: `"sidebar header toc"
+        "sidebar toc-popover toc"
+        "sidebar main toc" 1fr / minmax(var(--fd-sidebar-col), 1fr) minmax(0, calc(var(--fd-layout-width,97rem) - var(--fd-sidebar-width) - var(--fd-toc-width))) minmax(min-content, 1fr)`,
+          "--fd-docs-row-1": "var(--fd-banner-height, 0px)",
+          "--fd-docs-row-2": "calc(var(--fd-docs-row-1) + var(--fd-header-height))",
+          "--fd-docs-row-3": "calc(var(--fd-docs-row-2) + var(--fd-toc-popover-height))",
+          "--fd-sidebar-col": collapsed ? "0px" : "var(--fd-sidebar-width)",
+          ...style
+        } as object
+      }
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+export function LayoutTabs({
+  options,
+  ...props
+}: ComponentProps<"div"> & {
+  options: SidebarTab[];
+}) {
+  const pathname = usePathname();
+  const selected = useMemo(() => {
+    return options.findLast((option) => isTabActive(option, pathname));
+  }, [options, pathname]);
+
+  return (
+    <div
+      {...props}
+      className={cn(
+        "flex flex-row items-end gap-6 overflow-auto [grid-area:main]",
+        props.className
+      )}
+    >
+      {options.map((option, i) => (
+        <Link
+          key={i}
+          href={option.url}
+          className={cn(
+            "text-fd-muted-foreground hover:text-fd-accent-foreground inline-flex items-center gap-2 border-b-2 border-transparent pb-1.5 text-sm font-medium text-nowrap transition-colors",
+            option.unlisted && selected !== option && "hidden",
+            selected === option && "border-fd-primary text-fd-primary"
+          )}
+        >
+          {option.title}
+        </Link>
+      ))}
+    </div>
+  );
+}
+
+export function useIsScrollTop({ enabled = true }: { enabled?: boolean }) {
+  const [isTop, setIsTop] = useState<boolean | undefined>();
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const listener = () => {
+      setIsTop(window.scrollY < 10);
+    };
+
+    listener();
+    window.addEventListener("scroll", listener);
+    return () => {
+      window.removeEventListener("scroll", listener);
+    };
+  }, [enabled]);
+
+  return isTop;
+}