@barodoc/theme-docs 0.0.1 → 1.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Barocss
+Copyright (c) 2026 Barocss
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barodoc/theme-docs",
-  "version": "0.0.1",
+  "version": "1.0.1",
   "description": "Documentation theme for Barodoc",
   "type": "module",
   "exports": {
@@ -30,7 +30,7 @@
     "lucide-react": "^0.563.0",
     "mermaid": "^11.12.2",
     "tailwind-merge": "^3.4.0",
-    "@barodoc/core": "0.0.1"
+    "@barodoc/core": "1.0.1"
   },
   "peerDependencies": {
     "astro": "^5.0.0",

package/src/components/CodeCopy.astro

@@ -99,6 +99,46 @@
     border-radius: 0 !important;
     background: transparent !important;
   }
+
+  /* Inside CodeGroup: no extra border/background, add padding so code has internal spacing */
+  .code-group .code-block-wrapper {
+    margin: 0;
+    border: none;
+    border-radius: 0;
+    background: transparent;
+    /* padding: 1rem 1.25rem; */
+  }
+
+  .code-group .code-block-wrapper pre {
+    padding: 0 !important;
+  }
+
+  /* pre not wrapped by CodeCopy (direct child of code-group-content) */
+  .code-group .code-group-content > pre {
+    padding: 1rem 1.25rem !important;
+  }
+
+  /* CodeItem: one code block per tab; only the code area is visible, no extra wrapper space */
+  .code-group .code-item {
+    margin: 0;
+    padding: 0;
+    display: block;
+  }
+
+  .code-group .code-item:not(:first-child) {
+    display: none; /* toggled by CodeGroup script */
+  }
+
+  /* .code-group .code-item .code-block-wrapper,
+  .code-group .code-item > pre {
+    margin: 0 !important;
+    border: none !important;
+    padding: 0.25rem 0rem !important;
+  } */
+
+  /* .code-group .code-item .code-block-wrapper pre {
+    padding: 0 !important;
+  } */
   
   .code-block-header {
     display: flex;

package/src/components/DocHeader.tsx

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { Search, Menu, Moon, Sun, Github } from "lucide-react";
+import { Search, Menu, Moon, Sun, Github, Globe, ChevronDown } from "lucide-react";
 import { Button } from "./ui/button";
 import { Separator } from "./ui/separator";
 import {
@@ -17,6 +17,30 @@ interface DocHeaderProps {
   hasMultipleLocales?: boolean;
   currentLocale?: string;
   localeLabels?: Record<string, string>;
+  currentPath?: string;
+  locales?: string[];
+  defaultLocale?: string;
+}
+
+function getLocalizedUrl(
+  path: string,
+  locale: string,
+  defaultLocale: string,
+): string {
+  const docsPrefix = "/docs/";
+  const koPrefix = "/docs/ko/";
+
+  if (path.startsWith(koPrefix)) {
+    path = path === "/docs/ko" ? "/docs" : docsPrefix + path.slice(koPrefix.length);
+  }
+
+  if (locale === defaultLocale) {
+    return path || "/";
+  }
+  if (path === "/" || !path.startsWith(docsPrefix)) {
+    return path === "/" ? "/docs/ko/introduction" : path;
+  }
+  return docsPrefix + "ko/" + path.slice(docsPrefix.length);
 }
 
 export function DocHeader({
@@ -24,10 +48,25 @@ export function DocHeader({
   logo,
   githubUrl,
   hasMultipleLocales,
-  currentLocale,
-  localeLabels,
+  currentLocale = "en",
+  localeLabels = {},
+  currentPath = "",
+  locales = [],
+  defaultLocale = "en",
 }: DocHeaderProps) {
   const [theme, setTheme] = React.useState<"light" | "dark">("light");
+  const [langOpen, setLangOpen] = React.useState(false);
+  const langRef = React.useRef<HTMLDivElement>(null);
+
+  React.useEffect(() => {
+    const close = (e: MouseEvent) => {
+      if (langRef.current && !langRef.current.contains(e.target as Node)) {
+        setLangOpen(false);
+      }
+    };
+    document.addEventListener("click", close);
+    return () => document.removeEventListener("click", close);
+  }, []);
 
   React.useEffect(() => {
     const isDark = document.documentElement.classList.contains("dark");
@@ -51,21 +90,21 @@ export function DocHeader({
 
   return (
     <TooltipProvider>
-      <header className="sticky top-0 z-50 w-full border-b border-[var(--color-border)] bg-[var(--color-bg)]/95 backdrop-blur-md supports-[backdrop-filter]:bg-[var(--color-bg)]/80">
-        <div className="flex h-14 items-center justify-between px-4 max-w-[1120px] mx-auto">
+      <header className="sticky top-0 z-50 w-full min-w-0 border-b border-[var(--color-border)] bg-[var(--color-bg)]/95 backdrop-blur-md supports-[backdrop-filter]:bg-[var(--color-bg)]/80">
+        <div className="flex h-14 items-center justify-between gap-2 px-3 sm:px-4 max-w-[1120px] mx-auto min-w-0">
           {/* Logo */}
-          <div className="flex items-center gap-6">
+          <div className="flex items-center gap-6 min-w-0 shrink">
             <a
               href="/"
-              className="flex items-center gap-2.5 font-semibold text-[var(--color-text)] hover:opacity-80 transition-opacity"
+              className="flex items-center gap-2 min-w-0 shrink overflow-hidden font-semibold text-[var(--color-text)] hover:opacity-80 transition-opacity"
             >
-              {logo && <img src={logo} alt={siteName} className="h-7 w-7" />}
-              <span className="text-lg">{siteName}</span>
+              {logo && <img src={logo} alt={siteName} className="h-7 w-7 shrink-0" />}
+              <span className="text-lg truncate">{siteName}</span>
             </a>
           </div>
 
           {/* Right side actions */}
-          <div className="flex items-center gap-1">
+          <div className="flex items-center gap-1 shrink-0">
             {/* Search button */}
             <Button
               variant="outline"
@@ -124,6 +163,57 @@ export function DocHeader({
               </Tooltip>
             )}
 
+            {/* Language switcher */}
+            {hasMultipleLocales && locales.length > 0 && (
+              <>
+                <Separator orientation="vertical" className="hidden md:block h-6 mx-2" />
+                <div className="relative" ref={langRef}>
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <Button
+                        variant="ghost"
+                        className="rounded-xl gap-1 px-2"
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          setLangOpen((o) => !o);
+                        }}
+                      >
+                        <Globe className="h-4 w-4" />
+                        <span className="text-sm hidden sm:inline">
+                          {localeLabels[currentLocale] ?? currentLocale}
+                        </span>
+                        <ChevronDown className="h-3 w-3" />
+                        <span className="sr-only">Language</span>
+                      </Button>
+                    </TooltipTrigger>
+                    <TooltipContent>Language</TooltipContent>
+                  </Tooltip>
+                  {langOpen && (
+                    <div
+                      className="absolute right-0 mt-1 py-1 min-w-[8rem] rounded-lg border border-[var(--color-border)] bg-[var(--color-bg)] shadow-lg z-50"
+                      role="menu"
+                    >
+                      {locales.map((locale) => (
+                        <a
+                          key={locale}
+                          href={getLocalizedUrl(currentPath, locale, defaultLocale)}
+                          className={cn(
+                            "block px-3 py-2 text-sm transition-colors",
+                            locale === currentLocale
+                              ? "bg-primary-100 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300"
+                              : "text-[var(--color-text)] hover:bg-[var(--color-bg-secondary)]"
+                          )}
+                          role="menuitem"
+                        >
+                          {localeLabels[locale] ?? locale}
+                        </a>
+                      ))}
+                    </div>
+                  )}
+                </div>
+              </>
+            )}
+
             {/* Theme toggle */}
             <Tooltip>
               <TooltipTrigger asChild>

package/src/components/Header.astro

@@ -1,17 +1,16 @@
 ---
 import { DocHeader } from "./DocHeader";
-import LanguageSwitcher from "./LanguageSwitcher.astro";
 import config from "virtual:barodoc/config";
 import { locales, defaultLocale } from "virtual:barodoc/i18n";
 
 interface Props {
   currentLocale?: string;
+  currentPath?: string;
 }
 
-const { currentLocale = defaultLocale } = Astro.props;
+const { currentLocale = defaultLocale, currentPath = "" } = Astro.props;
 const hasMultipleLocales = locales.length > 1;
 
-// Build locale labels from config
 const localeLabels: Record<string, string> = config.i18n?.labels || {};
 ---
 
@@ -23,10 +22,7 @@ const localeLabels: Record<string, string> = config.i18n?.labels || {};
   hasMultipleLocales={hasMultipleLocales}
   currentLocale={currentLocale}
   localeLabels={localeLabels}
+  currentPath={currentPath}
+  locales={locales}
+  defaultLocale={defaultLocale}
 />
-
-{hasMultipleLocales && (
-  <div class="hidden">
-    <LanguageSwitcher currentLocale={currentLocale} />
-  </div>
-)}

package/src/components/LanguageSwitcher.astro

@@ -10,20 +10,22 @@ const { currentLocale } = Astro.props;
 const currentPath = Astro.url.pathname;
 
 function getLocalizedUrl(locale: string): string {
-  // Remove current locale from path if present
+  // URLs: /docs/... (en), /docs/ko/... (ko) — no /en/ or /ko/ prefix
   let path = currentPath;
-  for (const loc of locales) {
-    if (path.startsWith(`/${loc}/`) || path === `/${loc}`) {
-      path = path.slice(loc.length + 1) || "/";
-      break;
-    }
+  const docsPrefix = "/docs/";
+  const koPrefix = "/docs/ko/";
+
+  if (path.startsWith(koPrefix)) {
+    path = path === koPrefix.slice(0, -1) ? "/docs" : docsPrefix + path.slice(koPrefix.length);
   }
-  
-  // Add new locale
+
   if (locale === defaultLocale) {
-    return path;
+    return path || "/";
+  }
+  if (path === "/" || !path.startsWith(docsPrefix)) {
+    return path === "/" ? "/docs/ko/introduction" : path;
   }
-  return `/${locale}${path}`;
+  return docsPrefix + "ko/" + path.slice(docsPrefix.length);
 }
 ---
 

package/src/components/Sidebar.astro

@@ -19,16 +19,12 @@ function normalizePath(path: string): string {
 function isActive(page: string): boolean {
   const normalized = normalizePath(currentPath);
   const pagePath = normalizePath(page);
-  return normalized === pagePath || 
-    normalized === `docs/${pagePath}` ||
-    normalized === `${currentLocale}/docs/${pagePath}`;
+  const docsSlug = currentLocale === defaultLocale ? pagePath : `ko/${pagePath}`;
+  return normalized === `docs/${pagePath}` || normalized === `docs/${docsSlug}`;
 }
 
 function getPageHref(page: string): string {
-  if (currentLocale === defaultLocale) {
-    return `/docs/${page}`;
-  }
-  return `/${currentLocale}/docs/${page}`;
+  return currentLocale === defaultLocale ? `/docs/${page}` : `/docs/ko/${page}`;
 }
 
 // Get page title from the page slug

package/src/components/mdx/CodeGroup.astro

@@ -1,5 +1,7 @@
 ---
-// CodeGroup component for tabbed code blocks
+// CodeGroup component for tabbed code blocks.
+// When using CodeItem children, each CodeItem's title is used for the tab label.
+// Optional titles array is only used when not using CodeItem (direct pre children).
 interface Props {
   titles?: string[];
 }
@@ -7,9 +9,9 @@ interface Props {
 const { titles = [] } = Astro.props;
 ---
 
-<div class="not-prose my-4 code-group" data-titles={JSON.stringify(titles)}>
-  <div class="code-group-tabs flex border-b border-[var(--color-border)] bg-[var(--color-bg-secondary)] rounded-t-lg"></div>
-  <div class="code-group-content">
+<div class="code-group not-prose my-4 rounded-lg border border-[var(--color-border)] overflow-hidden" data-titles={JSON.stringify(titles)}>
+  <div class="code-group-tabs flex flex-wrap gap-0 border-b border-[var(--color-border)] bg-[var(--color-bg-tertiary)]"></div>
+  <div class="code-group-content bg-[var(--color-bg-secondary)]">
     <slot />
   </div>
 </div>
@@ -19,40 +21,50 @@ const { titles = [] } = Astro.props;
     document.querySelectorAll('.code-group').forEach((group) => {
       const tabsContainer = group.querySelector('.code-group-tabs');
       const contentContainer = group.querySelector('.code-group-content');
-      const titles = JSON.parse(group.getAttribute('data-titles') || '[]');
-      const codeBlocks = contentContainer?.querySelectorAll('pre');
+      const fallbackTitles = JSON.parse(group.getAttribute('data-titles') || '[]');
 
-      if (!tabsContainer || !contentContainer || !codeBlocks?.length) return;
+      const codeItems = contentContainer?.querySelectorAll(':scope > .code-item');
+      const directPres = contentContainer?.querySelectorAll(':scope > pre');
 
-      // Create tabs
-      codeBlocks.forEach((block, index) => {
+      // When CodeItem children exist: use them for tabs (titles from data-title), one tab per .code-item
+      const useCodeItems = (codeItems?.length ?? 0) > 0;
+      const tabPanels = useCodeItems
+        ? Array.from(codeItems!)
+        : Array.from(directPres || []);
+      const titles = useCodeItems && codeItems?.length
+        ? Array.from(codeItems!).map((el) => (el as HTMLElement).getAttribute('data-title') ?? '')
+        : fallbackTitles;
+      const numTabs = tabPanels.length;
+
+      if (!tabsContainer || !contentContainer || numTabs === 0) return;
+
+      // Create tabs from titles; show/hide tabPanels
+      tabPanels.forEach((_panel, index) => {
         const tab = document.createElement('button');
-        tab.className = 'px-4 py-2 text-sm font-medium transition-colors text-[var(--color-text-secondary)] hover:text-[var(--color-text)]';
-        tab.textContent = titles[index] || `Tab ${index + 1}`;
+        tab.className = 'shrink-0 px-4 py-2 text-sm font-medium transition-colors whitespace-nowrap text-[var(--color-text-muted)] hover:text-[var(--color-text)]';
+        tab.textContent = titles[index]?.trim() || `Tab ${index + 1}`;
+        const panel = tabPanels[index] as HTMLElement;
         tab.addEventListener('click', () => {
-          // Update tabs
           tabsContainer.querySelectorAll('button').forEach((t, i) => {
             if (i === index) {
-              t.classList.add('border-b-2', 'border-primary-600', 'text-primary-600');
-              t.classList.remove('text-[var(--color-text-secondary)]');
+              t.classList.add('border-b-2', 'border-primary-500', 'text-[var(--color-text)]', '-mb-px');
+              t.classList.remove('text-[var(--color-text-muted)]');
             } else {
-              t.classList.remove('border-b-2', 'border-primary-600', 'text-primary-600');
-              t.classList.add('text-[var(--color-text-secondary)]');
+              t.classList.remove('border-b-2', 'border-primary-500', 'text-[var(--color-text)]', '-mb-px');
+              t.classList.add('text-[var(--color-text-muted)]');
             }
           });
-          // Update content
-          codeBlocks.forEach((b, i) => {
-            (b as HTMLElement).style.display = i === index ? 'block' : 'none';
+          tabPanels.forEach((p, i) => {
+            (p as HTMLElement).style.display = i === index ? 'block' : 'none';
           });
         });
         tabsContainer.appendChild(tab);
 
-        // Hide all but first
         if (index === 0) {
-          tab.classList.add('border-b-2', 'border-primary-600', 'text-primary-600');
-          tab.classList.remove('text-[var(--color-text-secondary)]');
+          tab.classList.add('border-b-2', 'border-primary-500', 'text-[var(--color-text)]', '-mb-px');
+          tab.classList.remove('text-[var(--color-text-muted)]');
         } else {
-          (block as HTMLElement).style.display = 'none';
+          panel.style.display = 'none';
         }
       });
     });

package/src/components/mdx/CodeGroup.tsx

@@ -5,25 +5,91 @@ interface CodeGroupProps {
   titles?: string[];
 }
 
+function isCodeBlockLike(el: React.ReactElement): boolean {
+  if (el.type === "pre") return true;
+  const className =
+    typeof el.props?.className === "string" ? el.props.className : "";
+  if (
+    className.includes("language-") ||
+    className.includes("astro-code") ||
+    className.includes("code-block")
+  )
+    return true;
+  return false;
+}
+
+function collectCodeBlocks(node: React.ReactNode): React.ReactElement[] {
+  const result: React.ReactElement[] = [];
+  React.Children.forEach(node, (child) => {
+    if (!React.isValidElement(child)) return;
+    if (child.type === React.Fragment && child.props?.children != null) {
+      result.push(...collectCodeBlocks(child.props.children));
+      return;
+    }
+    if (child.type === "pre" || isCodeBlockLike(child)) {
+      result.push(child);
+      return;
+    }
+    if (child.props?.children != null) {
+      result.push(...collectCodeBlocks(child.props.children));
+    }
+  });
+  return result;
+}
+
 export function CodeGroup({ children, titles = [] }: CodeGroupProps) {
   const [activeIndex, setActiveIndex] = React.useState(0);
-  
-  // Extract code blocks from children
-  const codeBlocks = React.Children.toArray(children);
-  
+
+  const codeBlocks = React.useMemo(() => {
+    let blocks = collectCodeBlocks(children);
+    if (blocks.length > 0) return blocks;
+    const direct = React.Children.toArray(children).filter(
+      (c): c is React.ReactElement => React.isValidElement(c) && c.type != null
+    );
+    if (direct.length > 1) return direct;
+    if (
+      direct.length === 1 &&
+      direct[0].props?.children != null
+    ) {
+      const inner = React.Children.toArray(direct[0].props.children).filter(
+        (c): c is React.ReactElement =>
+          React.isValidElement(c) && c.type != null
+      );
+      if (inner.length > 0) return inner;
+    }
+    return direct;
+  }, [children]);
+
+  const tabTitles =
+    titles.length >= codeBlocks.length
+      ? titles.slice(0, codeBlocks.length)
+      : [
+          ...titles,
+          ...codeBlocks
+            .slice(titles.length)
+            .map((_, i) => `Tab ${titles.length + i + 1}`),
+        ];
+
+  if (codeBlocks.length === 0) {
+    return (
+      <div className="code-group not-prose my-4 rounded-lg border border-[var(--color-border)] overflow-hidden p-4 text-[var(--color-text-muted)] text-sm">
+        No code blocks found inside CodeGroup.
+      </div>
+    );
+  }
+
   return (
-    <div className="not-prose my-4 rounded-lg border border-[var(--color-border)] overflow-hidden">
+    <div className="code-group not-prose my-4 rounded-lg border border-[var(--color-border)] overflow-hidden">
       {/* Tabs */}
-      <div className="flex bg-[var(--color-bg-tertiary)] border-b border-[var(--color-border)]">
-        {codeBlocks.map((_, index) => {
+      <div className="flex flex-wrap gap-0 bg-[var(--color-bg-tertiary)] border-b border-[var(--color-border)]">
+        {tabTitles.map((title, index) => {
           const isActive = activeIndex === index;
-          const title = titles[index] || `Tab ${index + 1}`;
           return (
             <button
               key={index}
               type="button"
               onClick={() => setActiveIndex(index)}
-              className={`px-4 py-2 text-sm font-medium transition-colors ${
+              className={`shrink-0 px-4 py-2 text-sm font-medium transition-colors whitespace-nowrap ${
                 isActive
                   ? "bg-[var(--color-bg-secondary)] text-[var(--color-text)] border-b-2 border-primary-500 -mb-px"
                   : "text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
@@ -34,7 +100,7 @@ export function CodeGroup({ children, titles = [] }: CodeGroupProps) {
           );
         })}
       </div>
-      
+
       {/* Content */}
       <div className="bg-[var(--color-bg-secondary)]">
         {codeBlocks.map((block, index) => (

package/src/components/mdx/CodeItem.astro

@@ -0,0 +1,13 @@
+---
+// Wraps a single code block inside CodeGroup. Use one CodeItem per tab.
+// Put one fenced code block (```lang ... ```) inside; MDX/Shiki handle syntax highlighting.
+interface Props {
+  title?: string;
+}
+
+const { title = "" } = Astro.props;
+---
+
+<div class="code-item" data-title={title}>
+  <slot />
+</div>

package/src/index.ts

@@ -1,5 +1,5 @@
 import type { AstroIntegration } from "astro";
-import type { ThemeExport } from "@barodoc/core";
+import type { ThemeExport, ResolvedBarodocConfig } from "@barodoc/core";
 import mdx from "@astrojs/mdx";
 import react from "@astrojs/react";
 import tailwindcss from "@tailwindcss/vite";
@@ -8,7 +8,60 @@ export interface DocsThemeOptions {
   customCss?: string[];
 }
 
-function createThemeIntegration(options?: DocsThemeOptions): AstroIntegration {
+/** HAST node with optional children and properties */
+interface HastNode {
+  type: string;
+  children?: HastNode[];
+  properties?: Record<string, unknown>;
+  tagName?: string;
+  value?: string;
+}
+
+function getTextContent(node: HastNode): string {
+  if (node.type === "text") return node.value ?? "";
+  if (node.children?.length) return node.children.map(getTextContent).join("");
+  return "";
+}
+
+function isEmptyLine(node: HastNode): boolean {
+  if (node.type !== "element" || node.tagName !== "span") return false;
+  const cls = node.properties?.className;
+  const isLine =
+    Array.isArray(cls) && cls.some((c) => c === "line" || (typeof c === "string" && c.includes("line")));
+  if (!isLine) return false;
+  return /^\s*$/.test(getTextContent(node));
+}
+
+/** Removes leading and trailing empty span.line so only the code area is visible. */
+function createTrimEmptyLinesTransformer() {
+  return {
+    name: "barodoc-trim-empty-lines",
+    code(node: HastNode) {
+      const lines = node.children;
+      if (!lines?.length) return;
+      let start = 0;
+      let end = lines.length;
+      while (start < end && isEmptyLine(lines[start])) start++;
+      while (end > start && isEmptyLine(lines[end - 1])) end--;
+      node.children = lines.slice(start, end);
+    },
+  };
+}
+
+function createLineNumbersTransformer() {
+  return {
+    name: "barodoc-line-numbers",
+    pre(node: { properties?: Record<string, unknown> }) {
+      (this as { addClassToHast: (node: unknown, cls: string) => void }).addClassToHast(node, "line-numbers");
+    },
+  };
+}
+
+function createThemeIntegration(
+  config: ResolvedBarodocConfig,
+  options?: DocsThemeOptions
+): AstroIntegration {
+  const lineNumbers = config?.lineNumbers === true;
   return {
     name: "@barodoc/theme-docs",
     hooks: {
@@ -26,17 +79,6 @@ function createThemeIntegration(options?: DocsThemeOptions): AstroIntegration {
           entrypoint: "@barodoc/theme-docs/pages/docs/[...slug].astro",
         });
 
-        // Inject localized routes for non-default locales
-        injectRoute({
-          pattern: "/[locale]",
-          entrypoint: "@barodoc/theme-docs/pages/index.astro",
-        });
-
-        injectRoute({
-          pattern: "/[locale]/docs/[...slug]",
-          entrypoint: "@barodoc/theme-docs/pages/docs/[...slug].astro",
-        });
-
         // Update Astro config with integrations and Vite plugins
         updateConfig({
           integrations: [mdx(), react()],
@@ -52,6 +94,10 @@ function createThemeIntegration(options?: DocsThemeOptions): AstroIntegration {
                 light: "github-light",
                 dark: "github-dark",
               },
+              transformers: [
+                createTrimEmptyLinesTransformer(),
+                ...(lineNumbers ? [createLineNumbersTransformer()] : []),
+              ],
             },
           },
         });
@@ -65,7 +111,7 @@ function createThemeIntegration(options?: DocsThemeOptions): AstroIntegration {
 export default function docsTheme(options?: DocsThemeOptions): ThemeExport {
   return {
     name: "@barodoc/theme-docs",
-    integration: () => createThemeIntegration(options),
+    integration: (config) => createThemeIntegration(config, options),
     styles: options?.customCss || [],
   };
 }

package/src/layouts/DocsLayout.astro

@@ -30,11 +30,11 @@ const currentLocale = getLocaleFromPath(currentPath, i18nConfig);
 ---
 
 <BaseLayout title={title} description={description}>
-  <Header currentLocale={currentLocale} />
+  <Header currentLocale={currentLocale} currentPath={currentPath} />
   
   <!-- Centered container for docs layout -->
-  <div class="w-full min-h-[calc(100vh-3.5rem)] flex justify-center">
-    <div class="flex w-full max-w-[1120px]">
+  <div class="w-full min-w-0 min-h-[calc(100vh-3.5rem)] flex justify-center overflow-x-hidden">
+    <div class="flex w-full max-w-[1120px] min-w-0">
       <!-- Desktop Sidebar -->
       <aside class="hidden lg:block w-[220px] shrink-0">
         <div class="sticky top-14 h-[calc(100vh-3.5rem)] overflow-y-auto py-6 pr-4">
@@ -42,10 +42,10 @@ const currentLocale = getLocaleFromPath(currentPath, i18nConfig);
         </div>
       </aside>
 
-      <!-- Main Content -->
-      <main class="flex-1 min-w-0 min-w-[650px] max-w-[720px]">
-        <div class="px-8 py-8">
-          <article class="prose prose-gray dark:prose-invert max-w-none">
+      <!-- Main Content: no min-width on mobile to avoid horizontal scroll -->
+      <main class="flex-1 min-w-0 lg:min-w-[650px] max-w-[720px]">
+        <div class="px-4 py-6 sm:px-6 sm:py-8 lg:px-8 lg:py-8">
+          <article class="prose prose-gray dark:prose-invert max-w-none min-w-0 overflow-x-auto">
             <slot />
           </article>
           

package/src/pages/404.astro

@@ -0,0 +1,32 @@
+---
+import BaseLayout from "../layouts/BaseLayout.astro";
+import config from "virtual:barodoc/config";
+
+const pathname = new URL(Astro.request.url).pathname;
+---
+
+<BaseLayout title={`${config.name} · Page not found`} description="The page you are looking for does not exist.">
+  <div class="min-h-screen flex flex-col items-center justify-center px-4">
+    <div class="text-center max-w-md">
+      <p class="text-8xl font-bold text-[var(--color-text-muted)] select-none" aria-hidden="true">404</p>
+      <h1 class="text-2xl font-semibold text-[var(--color-text)] mt-4">Page not found</h1>
+      <p class="text-[var(--color-text-secondary)] mt-2">
+        The page at <code class="text-sm bg-[var(--color-bg-secondary)] px-2 py-1 rounded break-all">{pathname}</code> does not exist.
+      </p>
+      <div class="flex flex-col sm:flex-row items-center justify-center gap-3 mt-8">
+        <a
+          href="/"
+          class="px-5 py-2.5 bg-primary-600 text-white rounded-xl hover:bg-primary-700 transition-colors font-medium"
+        >
+          Home
+        </a>
+        <a
+          href="/docs/introduction"
+          class="px-5 py-2.5 border border-[var(--color-border)] text-[var(--color-text)] rounded-xl hover:bg-[var(--color-bg-secondary)] transition-colors font-medium"
+        >
+          Documentation
+        </a>
+      </div>
+    </div>
+  </div>
+</BaseLayout>

package/src/pages/docs/[...slug].astro

@@ -21,7 +21,7 @@ export async function getStaticPaths() {
       cleanSlug = slugParts.slice(1).join("/");
     }
     
-    // Build the path
+    // URL: /docs/introduction (en), /docs/ko/introduction (ko) — locale only inside slug
     const path = locale === defaultLocale 
       ? cleanSlug 
       : `${locale}/${cleanSlug}`;
@@ -71,12 +71,9 @@ function getPageTitle(slug: string): string {
     .join(' ');
 }
 
-// Get page href
+// Get page href (always /docs/...; non-default locale is inside slug)
 function getPageHref(slug: string): string {
-  if (locale === defaultLocale) {
-    return `/docs/${slug}`;
-  }
-  return `/${locale}/docs/${slug}`;
+  return `/docs/${locale === defaultLocale ? slug : `${locale}/${slug}`}`;
 }
 
 // Find prev/next pages

package/src/styles/global.css

@@ -63,6 +63,7 @@
     background-color: var(--color-bg);
     color: var(--color-text);
     font-feature-settings: "rlig" 1, "calt" 1;
+    overflow-x: hidden;
   }
 
   /* Smooth transitions for all interactive elements */
@@ -76,29 +77,29 @@
   }
 }
 
-/* Prose styling for MDX content - Mintlify style */
+/* Prose styling for MDX content -  */
 .prose {
   --tw-prose-body: var(--color-text);
   --tw-prose-headings: var(--color-text);
   --tw-prose-links: var(--color-primary-600);
   --tw-prose-code: var(--color-text);
   --tw-prose-pre-bg: var(--color-bg-secondary);
-  font-size: 0.875rem !important;
-  line-height: 1.6 !important;
+  /* font-size: 0.875rem !important; */
+  /* line-height: 1.6 !important; */
 }
 
 .dark .prose {
   --tw-prose-links: var(--color-primary-400);
 }
 
-/* Headings - Mintlify style */
+/* Headings -  */
 .prose :where(h1):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
   font-size: 1.75rem !important;
   font-weight: 700 !important;
   letter-spacing: -0.025em !important;
   margin-top: 0 !important;
   margin-bottom: 0.375rem !important;
-  line-height: 1.25 !important;
+  /* line-height: 1.25 !important; */
 }
 
 .prose :where(h2):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
@@ -142,14 +143,14 @@
   text-underline-offset: 2px !important;
 }
 
-/* Code block styling - Mintlify style */
+/* Code block styling -  */
 .prose :where(pre):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
   background-color: var(--color-bg) !important;
   border: 1px solid var(--color-border) !important;
   border-radius: 0.5rem !important;
   padding: 0.75rem 1rem !important;
   font-size: 0.8125rem !important;
-  line-height: 1.5 !important;
+  line-height: 1.45 !important;
   overflow-x: auto !important;
   margin: 0.75rem 0 !important;
 }
@@ -184,7 +185,7 @@
   color: var(--color-text-muted) !important;
 }
 
-/* Blockquotes - Mintlify style */
+/* Blockquotes -  */
 .prose :where(blockquote):not(:where([class~="not-prose"],[class~="not-prose"] *)) {
   border-left: 3px solid var(--color-primary-500) !important;
   background-color: var(--color-bg-secondary) !important;
@@ -240,6 +241,20 @@
 .astro-code {
   background-color: var(--color-bg) !important;
   border-radius: 0.5rem;
+  line-height: 1.45;
+}
+
+.astro-code code {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Tighter line spacing: Shiki outputs each line as span.line */
+.astro-code span.line {
+  display: block;
+  line-height: 1.45;
+  margin: 0;
+  padding: 0;
 }
 
 .dark .astro-code,
@@ -248,6 +263,28 @@
   background-color: var(--shiki-dark-bg) !important;
 }
 
+/* Line numbers: applied when barodoc.config.json has "lineNumbers": true */
+.astro-code.line-numbers {
+  counter-reset: line;
+}
+
+.astro-code.line-numbers span.line {
+  display: block;
+  counter-increment: line;
+}
+
+.astro-code.line-numbers span.line::before {
+  content: counter(line);
+  display: inline-block;
+  min-width: 2.5rem;
+  margin-right: 1rem;
+  padding-right: 0.5rem;
+  text-align: right;
+  color: var(--color-text-muted);
+  user-select: none;
+  border-right: 1px solid var(--color-border);
+}
+
 /* Pagefind search styling */
 .pagefind-ui {
   --pagefind-ui-scale: 1;