@docubook/flame 1.3.8 → 1.4.1

package/.docu/components/Context.tsx

@@ -3,7 +3,7 @@
 import { useState } from "react";
 import { cn } from "../node/utils";
 import { Dropdown, DropdownItem } from "@docubook/ui-react/dropdown";
-import { routes } from "../node/client-routes";
+import { routes, config as docuConfig } from "../node/client-routes";
 import { ChevronsUpDown, Check } from "lucide-react";
 import { renderLucideIcon } from "./Lucide";
 
@@ -30,6 +30,9 @@ export function Context({ className }: ContextProps) {
     typeof window !== "undefined" ? window.location.pathname : "/"
   );
   const mounted = typeof window !== "undefined";
+
+  const mode = docuConfig.sidebar?.context || "dropdown";
+  if (mode === "separator") return null;
   const activeRoute = pathname.startsWith("/docs") ? getActiveContextRoute(pathname) : undefined;
   const contextRoutes = getContextRoutes();
   const fallbackRoute = routes[0];

package/.docu/components/Menu.tsx

@@ -2,8 +2,10 @@
 
 import { useState } from "react";
 import Sublink from "./Sublink";
+import SidebarGroupHeader from "./SidebarGroupHeader";
 import type { DocuRoute } from "../node/types";
 import { cn } from "../node/utils";
+import { config as docuConfig } from "../node/client-routes";
 
 interface MenuProps {
   onNavigate?: () => void;
@@ -33,6 +35,85 @@ export default function Menu({ onNavigate, className = "", pathname, routes = []
 
   if (!currentPath.startsWith("/docs")) return null;
 
+  const mode = docuConfig.sidebar?.context || "dropdown";
+
+  // Helper: check if a sublink under a given route matches the current path
+  const isItemActive = (itemHref: string, parentRouteHref: string) => {
+    const fullHref = `/docs${parentRouteHref}${itemHref}`;
+    return currentPath === fullHref || currentPath === `${fullHref}.html`;
+  };
+
+  // Separator mode: render all context sections as group headers + nav items
+  if (mode === "separator") {
+    const contextRoutes = menuRoutes.filter((r) => r.context);
+
+    // No context routes defined — fall back to flat list of all routes
+    if (contextRoutes.length === 0) {
+      return (
+        <nav
+          aria-label="Documentation navigation"
+          className={cn("transition-all duration-200", className)}
+        >
+          <ul className="flex flex-col gap-1.5 py-4">
+            {menuRoutes.map((route) => (
+              <li key={route.href}>
+                <Sublink
+                  {...route}
+                  href={route.href}
+                  level={0}
+                  onNavigate={onNavigate}
+                  parentHref="/docs"
+                />
+              </li>
+            ))}
+          </ul>
+        </nav>
+      );
+    }
+
+    return (
+      <nav
+        aria-label="Documentation navigation"
+        className={cn("transition-all duration-200", className)}
+      >
+        {contextRoutes.map((route, i) => (
+          <div key={route.href} className={i > 0 ? "mt-6 lg:mt-8" : ""}>
+            <SidebarGroupHeader
+              icon={route.context?.icon}
+              title={route.context?.title || route.title}
+            />
+            <ul className="border-base-300 flex flex-col gap-1.5 border-l-2 pb-0.5 pl-3 pt-0.5">
+              {route.items?.map((item) => {
+                const isActive = isItemActive(item.href, route.href);
+                return (
+                  <li key={item.href}>
+                    <div
+                      className={cn(
+                        "-ml-[14px] border-l-2",
+                        isActive ? "border-primary" : "border-transparent"
+                      )}
+                    >
+                      <div className="pl-3">
+                        <Sublink
+                          {...item}
+                          href={item.href}
+                          level={0}
+                          onNavigate={onNavigate}
+                          parentHref={`/docs${route.href}`}
+                        />
+                      </div>
+                    </div>
+                  </li>
+                );
+              })}
+            </ul>
+          </div>
+        ))}
+      </nav>
+    );
+  }
+
+  // Dropdown mode: render only the active context section
   const isDocsRoot = currentPath === "/docs" || currentPath === "/docs/";
   const currentContext = isDocsRoot
     ? menuRoutes[0]?.href.replace(/^\/+|\/+$/, "")

package/.docu/components/SidebarGroupHeader.tsx

@@ -0,0 +1,21 @@
+import { renderLucideIcon } from "./Lucide";
+
+interface SidebarGroupHeaderProps {
+  icon?: string;
+  title: string;
+}
+
+export default function SidebarGroupHeader({ icon, title }: SidebarGroupHeaderProps) {
+  return (
+    <div className="sidebar-group-header mb-1.5 flex items-center gap-2.5 font-medium text-gray-900 dark:text-gray-200">
+      {icon && (
+        <span className="flex h-4 w-4 shrink-0 items-center justify-center">
+          {renderLucideIcon(icon, "h-3.5 w-3.5")}
+        </span>
+      )}
+      <h3 className="sidebar-title font-[inherit] text-[length:inherit] leading-[inherit]">
+        <span>{title}</span>
+      </h3>
+    </div>
+  );
+}

package/.docu/components/Sublink.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { useState, useRef, useEffect } from "react";
 import { ChevronDown } from "lucide-react";
 import Anchor from "./Anchor";
 import type { DocuRoute } from "../node/types";
@@ -35,11 +35,17 @@ export default function Sublink({
 
   // Shared padding based on nesting level
   const levelPadding = cn(level === 1 && "pl-2", level === 2 && "pl-4", level >= 3 && "pl-6");
+  const isActive = currentPathname === fullHref || currentPathname === `${fullHref}.html`;
+  const activeRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (isActive && activeRef.current) {
+      activeRef.current.scrollIntoView({ block: "nearest" });
+    }
+  }, [isActive]);
 
   // Leaf node (no children)
   if (!items) {
-    const isActive = currentPathname === fullHref || currentPathname === `${fullHref}.html`;
-
     const link = (
       <Anchor
         href={fullHref}
@@ -51,8 +57,10 @@ export default function Sublink({
         {title}
       </Anchor>
     );
+
     return (
       <div
+        ref={activeRef}
         className={cn(
           "py-1.5",
           levelPadding,
@@ -67,7 +75,7 @@ export default function Sublink({
 
   // Section with children
   return (
-    <div className={cn("flex flex-col", levelPadding)}>
+    <div ref={isActive ? activeRef : undefined} className={cn("flex flex-col", levelPadding)}>
       {/* Section header */}
       <button
         type="button"

package/.docu/node/client-routes.ts

@@ -1,5 +1,5 @@
-import type { DocuRoute } from "./types";
+import type { DocuRoute, DocuConfig } from "./types";
 import docuConfig from "../../docu.json" with { type: "json" };
 
 export const routes: DocuRoute[] = docuConfig.routes || [];
-export const config = docuConfig;
+export const config = docuConfig as unknown as DocuConfig;

package/.docu/node/helpers.ts

@@ -4,11 +4,32 @@ import type { SocialLink } from "./types";
 const docuConfig = loadDocuConfig();
 
 export function getEditLink(url: string, filePath: string): string {
-  const configPath = docuConfig?.repo?.path || "blob/main/{filePath}";
+  const configPath = docuConfig?.repo?.path || detectPlatformPath(url);
   const encodedPath = filePath.replace(/^\//, "").split("/").map(encodeURIComponent).join("/");
   return `${url}/${configPath}`.replace("{filePath}", encodedPath);
 }
 
+/**
+ * Detect the default edit path template from the repo URL hostname.
+ * Supports GitHub, GitLab, Bitbucket, Gitea (cloud + self-hosted),
+ * Gogs, Forgejo, and Codeberg.
+ * Falls back to Gitea-style for unknown hosts — override via repo.path.
+ */
+export function detectPlatformPath(url: string): string {
+  try {
+    const host = new URL(url).hostname;
+    if (host === "github.com") return "blob/main/{filePath}";
+    if (host === "gitlab.com") return "-/blob/main/{filePath}";
+    if (host === "bitbucket.org") return "src/main/{filePath}";
+    if (host === "gitea.com") return "src/branch/main/{filePath}";
+    if (host === "codeberg.org") return "src/branch/main/{filePath}";
+    // Gogs, Forgejo, or any self-hosted Gitea-compatible forge
+    return "src/branch/main/{filePath}";
+  } catch {
+    return "blob/main/{filePath}";
+  }
+}
+
 export function isEditEnabled(): boolean {
   return docuConfig?.repo?.edit ?? false;
 }

package/.docu/node/types.ts

@@ -34,6 +34,13 @@ export interface DocuFooter {
   social: SocialLink[];
 }
 
+export interface DocuSidebar {
+  /** How context sections are displayed.
+   *  "dropdown" — context switcher dropdown (default)
+   *  "separator" — inline group headers in sidebar */
+  context?: "dropdown" | "separator";
+}
+
 export interface RepoConfig {
   url: string;
   path: string;
@@ -75,6 +82,7 @@ export interface DocuConfig {
   navbar: DocuNavbar;
   footer: DocuFooter;
   repo: RepoConfig;
+  sidebar?: DocuSidebar;
   routes: DocuRoute[];
   themes?: {
     colors: ThemeConfig;

package/README.md

@@ -105,14 +105,91 @@ bun run deploy    # Build + prepare for GitHub Pages
   },
   "repo": {
     "url": "https://github.com/you/repo",
-    "path": "blob/main/{filePath}",
     "edit": true
   },
   "routes": []
 }
 ```
 
-### Home Page
+### Repo & Edit Links
+
+The `repo` section enables **"Edit this page"** links on every doc page, pointing directly to the source file in your repository.
+
+```json
+{
+  "repo": {
+    "url": "https://github.com/you/repo",
+    "edit": true
+  }
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `url` | `string` (URI) | ✅ Yes | Base URL of your repository |
+| `edit` | `boolean` | ✅ Yes | Show or hide the edit link on pages |
+| `path` | `string` | No | Path template override — see below |
+
+#### Platform Auto-Detection
+
+When `path` is omitted, Flame detects the correct path format from `url` automatically:
+
+| Platform | Domain | Auto-generated path |
+|----------|--------|---------------------|
+| GitHub | `github.com` | `blob/main/{filePath}` |
+| GitLab | `gitlab.com` | `-/blob/main/{filePath}` |
+| Bitbucket | `bitbucket.org` | `src/main/{filePath}` |
+| Gitea Cloud | `gitea.com` | `src/branch/main/{filePath}` |
+| Codeberg (Forgejo) | `codeberg.org` | `src/branch/main/{filePath}` |
+| Gogs / self-hosted Gitea / Forgejo | any other host | `src/branch/main/{filePath}` |
+
+For most single-repo projects this is all you need — just set `url` and `edit: true`.
+
+#### When to set `path` manually
+
+Override `path` when auto-detection is not enough. The value must contain `{filePath}` as a placeholder:
+
+**Monorepo** — docs live in a subdirectory, not the repo root:
+
+```json
+{
+  "repo": {
+    "url": "https://github.com/org/monorepo",
+    "path": "blob/main/apps/docs/{filePath}",
+    "edit": true
+  }
+}
+```
+
+**Non-default branch** — your default branch is not `main`:
+
+```json
+{
+  "repo": {
+    "url": "https://github.com/you/repo",
+    "path": "blob/master/{filePath}",
+    "edit": true
+  }
+}
+```
+
+**Self-hosted GitLab on a custom domain** — auto-detect falls back to Gitea format, which is wrong for GitLab:
+
+```json
+{
+  "repo": {
+    "url": "https://git.mycompany.com/team/repo",
+    "path": "-/blob/main/{filePath}",
+    "edit": true
+  }
+}
+```
+
+> **Rule of thumb:** if your docs are at the root of the repo and the branch is `main`, skip `path` — auto-detect handles it. Add `path` only when you need to point to a subdirectory, a different branch, or a self-hosted platform with a non-standard URL format.
+
+
+
+### Homepage
 
 The `home` section configures your landing page with a hero section and feature cards:
 
@@ -212,6 +289,43 @@ Theme resolution follows this order (first match wins):
 
 ---
 
+### Sidebar
+
+Controls how documentation sections appear in the sidebar. Defaults to **dropdown** mode when not configured.
+
+To switch to **separator** mode, add `sidebar` to the top level of your `docu.json`:
+
+```json
+{
+  "sidebar": {
+    "context": "separator"
+  }
+}
+```
+
+| Mode | Description |
+|------|-------------|
+| `"dropdown"` (default) | Compact view — a dropdown at the top of the sidebar lets users switch between sections. Only the active section's items are shown. |
+| `"separator"` | All sections visible — group header (icon + title) with tree connector line. Items nest under their section. |
+
+```
+  Default (dropdown)              Separator
+  ┌──────────────────┐       📖 Guides
+  │  📖 Guides  ▼    │       │
+  ├──────────────────┤       ├─ Introduction
+  │  Introduction    │       ├─ Installation
+  │  Installation    │       │
+  └──────────────────┘       🧩 Markdown
+                              │
+                              ├─ Accordion
+                              ├─ Button
+                              └─ Card
+```
+
+> Omit `sidebar` entirely → dropdown mode. Set `"context": "separator"` → separator mode. Mode is static per page, no runtime switching.
+
+---
+
 ### Routes
 
 When `routes` is an empty array `[]`, Flame automatically scans your `docs/` folder at build-time and generates the sidebar navigation from the directory structure. Folders become collapsible sections, and `.mdx`/`.md` files become links — sorted alphabetically.
@@ -241,6 +355,8 @@ To define navigation manually, populate the `routes` array:
 
 > Manual routes take priority — if `routes` has entries, folder scanning is skipped entirely.
 
+> Context on a route (`icon`, `title`, `description`) provides metadata for the sidebar context switcher. In **dropdown** mode it fills the dropdown; in **separator** mode it renders the group header + tree. The icon name must match a [Lucide icon](https://lucide.dev/icons) export (e.g., `"BookOpen"`, `"Layers"`).
+
 ---
 
 ## Routing

package/docu.schema.json

@@ -105,14 +105,49 @@
       "description": "Repository configuration for edit links",
       "additionalProperties": false,
       "properties": {
-        "url": { "type": "string", "description": "Repository URL" },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Repository base URL. Supported platforms: GitHub, GitLab, Bitbucket, Gitea (gitea.com), Codeberg (codeberg.org), Gogs, Forgejo, or any self-hosted Gitea-compatible forge.",
+          "examples": [
+            "https://github.com/owner/repo",
+            "https://gitlab.com/owner/repo",
+            "https://bitbucket.org/owner/repo",
+            "https://gitea.com/owner/repo",
+            "https://codeberg.org/owner/repo"
+          ]
+        },
         "path": {
           "type": "string",
-          "description": "Path template for edit links. Use {filePath} as placeholder."
+          "description": "Path template for edit links. Must contain {filePath} as a placeholder. Format: {platform-path}/{optional-subdir}/{filePath}. Leave empty to auto-detect from repo.url hostname.",
+          "pattern": "\\{filePath\\}",
+          "examples": [
+            "blob/main/{filePath}",
+            "blob/main/apps/web/{filePath}",
+            "blob/develop/{filePath}",
+            "-/blob/main/{filePath}",
+            "-/blob/main/docs/{filePath}",
+            "src/main/{filePath}",
+            "src/branch/main/{filePath}",
+            "src/branch/main/docs/{filePath}"
+          ]
         },
         "edit": { "type": "boolean", "description": "Enable edit link on pages" }
       }
     },
+    "sidebar": {
+      "type": "object",
+      "description": "Sidebar configuration",
+      "additionalProperties": false,
+      "properties": {
+        "context": {
+          "type": "string",
+          "enum": ["dropdown", "separator"],
+          "default": "dropdown",
+          "description": "How context sections are displayed in sidebar — dropdown (switcher) or separator (inline group headers)"
+        }
+      }
+    },
     "routes": {
       "type": "array",
       "description": "Documentation navigation routes. Leave empty for auto-detection from docs/ folder.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docubook/flame",
-  "version": "1.3.8",
+  "version": "1.4.1",
   "description": "A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.",
   "type": "module",
   "bin": {
@@ -52,8 +52,8 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "unified": "^11.0.0",
-    "@docubook/core": "^1.7.2",
-    "@docubook/mdx-content": "^3.2.2",
+    "@docubook/core": "^1.8.0",
+    "@docubook/mdx-content": "^3.3.0",
     "@docubook/themes-colors": "^0.10.2",
     "@docubook/ui-react": "^0.1.4"
   },