@docubook/flame 1.4.2 → 1.4.3

package/.docu/components/Context.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useState } from "react";
-import { cn } from "../node/utils";
+import { cn, docsHtmlHref } from "../node/utils";
 import { Dropdown, DropdownItem } from "@docubook/ui-react/dropdown";
 import { routes, config as docuConfig } from "../node/client-routes";
 import { ChevronsUpDown, Check } from "lucide-react";
@@ -68,7 +68,7 @@ export function Context({ className }: ContextProps) {
       {contextRoutes.map((route) => {
         const isActive = activeRoute?.href === route.href;
         const firstItemPath = getFirstItemHref(route);
-        const contextPath = `/docs${firstItemPath}`;
+        const contextPath = docsHtmlHref(`/docs${firstItemPath}`);
 
         return (
           <DropdownItem

package/.docu/components/Pagination.tsx

@@ -2,6 +2,7 @@
 
 import type { ReactNode } from "react";
 import { getPreviousNext } from "../node/route";
+import { docsHtmlHref } from "../node/utils";
 import { PaginationDocs } from "@docubook/ui-react/pagination";
 
 interface PaginationProps {
@@ -27,8 +28,8 @@ export default function Pagination({
 
   return (
     <PaginationDocs
-      prev={prev ? { href: `/docs${prev.href}`, title: prev.title } : undefined}
-      next={next ? { href: `/docs${next.href}`, title: next.title } : undefined}
+      prev={prev ? { href: docsHtmlHref(`/docs${prev.href}`), title: prev.title } : undefined}
+      next={next ? { href: docsHtmlHref(`/docs${next.href}`), title: next.title } : undefined}
       className={className}
       prevIcon={prevIcon}
       nextIcon={nextIcon}

package/.docu/components/Sublink.tsx

@@ -4,7 +4,7 @@ import { useState, useRef, useEffect } from "react";
 import { ChevronDown } from "lucide-react";
 import Anchor from "./Anchor";
 import type { DocuRoute } from "../node/types";
-import { cn } from "../node/utils";
+import { cn, docsHtmlHref } from "../node/utils";
 
 interface SublinkProps extends DocuRoute {
   level: number;
@@ -48,7 +48,7 @@ export default function Sublink({
   if (!items) {
     const link = (
       <Anchor
-        href={fullHref}
+        href={docsHtmlHref(fullHref)}
         className="text-foreground hover:text-foreground/80 text-sm transition-colors"
         activeClassName="text-primary font-medium"
         activeWhen={(path) => path === fullHref || path === `${fullHref}.html`}
@@ -91,7 +91,7 @@ export default function Sublink({
           <span>{title}</span>
         ) : (
           <Anchor
-            href={fullHref}
+            href={docsHtmlHref(fullHref)}
             className="text-foreground hover:text-foreground/80 transition-colors"
             activeClassName="text-primary"
             activeWhen={(path) => path === fullHref || path === `${fullHref}.html`}

package/.docu/node/mdx.ts

@@ -11,6 +11,96 @@ import {
 import { createMdxComponents } from "@docubook/mdx-content";
 import { getGitLastModified, getGitLastModifiedBatch } from "./utils";
 
+/**
+ * Return the value with `.html` appended, or null if the value should be left
+ * unchanged.  Rules:
+ *  - Must be a string
+ *  - Must start with /docs/  (the /docs root index needs no suffix)
+ *  - Must not be an external URL, contain a fragment, or already end in .html
+ */
+function appendHtml(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  if (/^https?:\/\//.test(value)) return null;
+  if (!value.startsWith("/docs/")) return null;
+  if (value.includes("#")) return null;
+  if (value.endsWith(".html")) return null;
+  return `${value}.html`;
+}
+
+interface HastNode {
+  type: string;
+  tagName?: string;
+  properties?: Record<string, unknown>;
+  children?: HastNode[];
+}
+
+interface MdastNode {
+  type: string;
+  // MDX JSX nodes carry their props as an attributes array
+  attributes?: { type: string; name: string; value: unknown }[];
+  children?: MdastNode[];
+}
+
+/**
+ * Rehype plugin: append `.html` to internal `/docs/` hrefs on HTML `<a>` nodes.
+ *
+ * This covers standard markdown links: `[text](/docs/page)` → `<a href="…">`.
+ * It runs in the HAST (HTML AST) phase, where `<a>` elements are real nodes.
+ *
+ * Skips: external URLs, anchor-only links, paths that already end in `.html`,
+ * and the `/docs` root index (no trailing slash segment).
+ */
+function rehypeDocsHtmlLinks() {
+  return (tree: HastNode) => {
+    function walk(node: HastNode): void {
+      if (node.type === "element" && node.tagName === "a") {
+        const fixed = appendHtml(node.properties?.href);
+        if (fixed) node.properties!.href = fixed;
+      }
+      if (node.children) {
+        for (const child of node.children) walk(child);
+      }
+    }
+    walk(tree);
+    return tree;
+  };
+}
+
+/**
+ * Remark plugin: append `.html` to internal `/docs/` hrefs on MDX JSX nodes.
+ *
+ * MDX JSX elements (`<Card href="…">`, `<LinkCard href="…">`, etc.) live in
+ * the MDAST as `mdxJsxFlowElement` / `mdxJsxTextElement` nodes.  They are
+ * compiled directly to JavaScript by the MDX compiler *before* rehype runs,
+ * so a rehype plugin can never see them as `<a>` elements.  This remark plugin
+ * intercepts them at the MDAST phase where their `attributes` array is still
+ * accessible and mutable.
+ *
+ * Skips: same rules as `appendHtml` (external URLs, anchors, already `.html`).
+ */
+function remarkMdxJsxDocsHtmlLinks() {
+  return (tree: MdastNode) => {
+    function walk(node: MdastNode): void {
+      if (
+        (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") &&
+        node.attributes
+      ) {
+        for (const attr of node.attributes) {
+          if (attr.type === "mdxJsxAttribute" && attr.name === "href") {
+            const fixed = appendHtml(attr.value);
+            if (fixed) attr.value = fixed;
+          }
+        }
+      }
+      if (node.children) {
+        for (const child of node.children) walk(child);
+      }
+    }
+    walk(tree);
+    return tree;
+  };
+}
+
 export { getGitLastModifiedBatch };
 
 export interface MdxResult {
@@ -46,8 +136,11 @@ export async function compileMdx(
   const defaultRemark = createDefaultRemarkPlugins();
   const defaultRehype = createDefaultRehypePlugins();
 
-  const finalRemark = remarkPlugins?.length ? [...defaultRemark, ...remarkPlugins] : defaultRemark;
-  const finalRehype = rehypePlugins?.length ? [...defaultRehype, ...rehypePlugins] : defaultRehype;
+  // remarkMdxJsxDocsHtmlLinks must run before user plugins so custom remark
+  // transforms see already-fixed hrefs.  rehypeDocsHtmlLinks handles plain
+  // markdown [text](path) → <a> elements in the HAST phase.
+  const finalRemark = [...defaultRemark, remarkMdxJsxDocsHtmlLinks, ...(remarkPlugins ?? [])];
+  const finalRehype = [...defaultRehype, rehypeDocsHtmlLinks, ...(rehypePlugins ?? [])];
 
   const serialized = await serialize(strippedContent, {
     mdxOptions: {

package/.docu/node/search-indexer.ts

@@ -15,7 +15,7 @@ import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { resolve, join } from "node:path";
 import { extractFrontmatterWithContent } from "@docubook/core";
 import { DOCS_DIR, ASSETS_DIR, loadDocuConfig } from "./paths";
-import { scanMdxFiles } from "./utils";
+import { scanMdxFiles, docsHtmlHref } from "./utils";
 
 const docuConfig = loadDocuConfig();
 
@@ -72,7 +72,7 @@ export function stripJsx(content: string): string {
 export function extractRecords(filePath: string, raw: string): SearchRecord[] {
   const { frontmatter, strippedContent: content } = extractFrontmatterWithContent<Frontmatter>(raw);
   const records: SearchRecord[] = [];
-  const url = `/docs/${filePath}`;
+  const url = docsHtmlHref(`/docs/${filePath}`);
   const lvl0 = getSectionTitle(filePath);
   const lvl1 = frontmatter.title || null;
 

package/.docu/node/server.ts

@@ -16,6 +16,7 @@ import {
   type ServerState,
 } from "./server-routes";
 import { wrapPluginResponse } from "./security";
+import { stripDocsHtmlSuffix } from "./utils";
 
 const docuConfig = loadDocuConfig();
 
@@ -103,7 +104,9 @@ const server = Bun.serve({
 
   async fetch(req) {
     const url = new URL(req.url);
-    const pathname = url.pathname;
+    // Generated links carry `.html` (matching the static build output);
+    // route them to the same handler as their extensionless form.
+    const pathname = stripDocsHtmlSuffix(url.pathname);
     const startTime = performance.now();
 
     if (builder) {
@@ -150,7 +153,7 @@ const server = Bun.serve({
         if (staticRes) return staticRes;
       }
 
-      const match = router?.match(req);
+      const match = router?.match(pathname);
       let response: Response;
 
       if (match) {

package/.docu/node/types.ts

@@ -1,3 +1,6 @@
+import type { ThemeConfig } from "@docubook/themes-colors";
+import type { PluginEntry } from "./plugin";
+
 export interface DocuRouteContext {
   title?: string;
   icon?: string;
@@ -73,9 +76,6 @@ export interface HomeConfig {
   features?: HomeFeature[];
 }
 
-import type { ThemeConfig } from "@docubook/themes-colors";
-import type { PluginEntry } from "./plugin";
-
 export interface DocuConfig {
   meta: DocuMeta;
   home?: HomeConfig;

package/.docu/node/utils.ts

@@ -44,6 +44,20 @@ export function isExternalUrl(url: string): boolean {
   return /^(https?:\/\/|\/\/)/.test(url);
 }
 
+/** Suffix an internal docs link with `.html` to match the flat static build output. */
+export function docsHtmlHref(path: string): string {
+  return `${path}.html`;
+}
+
+/** Map a `/docs{.html,/*.html}` request back to its extensionless route (dev server).
+ *  Handles both `/docs/*.html` (pages) and `/docs.html` (edge case). */
+export function stripDocsHtmlSuffix(pathname: string): string {
+  if (pathname === "/docs.html") return "/docs";
+  if (pathname.startsWith("/docs/") && pathname.endsWith(".html"))
+    return pathname.slice(0, -".html".length);
+  return pathname;
+}
+
 export function getPath(url: string): string {
   try {
     return new URL(url).pathname;

package/.docu/pages/index.tsx

@@ -1,4 +1,5 @@
 import { loadDocuConfig } from "../node/paths";
+import { docsHtmlHref, isExternalUrl } from "../node/utils";
 import { Hero, Features } from "../components/home";
 import type { HomeFeature } from "../node/types";
 
@@ -21,23 +22,42 @@ export default function IndexPage() {
   const { meta, home } = docuConfig;
   const routes = (docuConfig.routes as RouteItem[]) || [];
 
+  // Docs pages under /docs/ are flat .html files; the root /docs is
+  // docs/index.html via directory index — no .html suffix needed.
+  const linkWithHtml = (link: string) => {
+    if (isExternalUrl(link)) return link;
+    if (link.startsWith("/docs/")) return `${link}.html`;
+    return link;
+  };
+
   // Use home.features if configured, otherwise fallback to routes with context
   const features: HomeFeature[] =
-    home?.features ||
+    home?.features?.map((f) => ({
+      ...f,
+      link: f.link ? linkWithHtml(f.link) : undefined,
+    })) ||
     routes
       .filter((r) => r.context)
       .map((route) => ({
         icon: route.context?.icon,
         title: route.context?.title || route.title,
         description: route.context?.description || "",
-        link: `/docs${route.href}${route.items?.[0]?.href || ""}`,
+        link: docsHtmlHref(`/docs${route.href}${route.items?.[0]?.href || ""}`),
       }));
 
   // Use home.hero if configured, otherwise fallback to meta
-  const hero = home?.hero || {
-    headline: meta.title,
-    description: meta.description,
-  };
+  const hero = home?.hero
+    ? {
+        ...home.hero,
+        actions: home.hero.actions?.map((a) => ({
+          ...a,
+          link: linkWithHtml(a.link),
+        })),
+      }
+    : {
+        headline: meta.title,
+        description: meta.description,
+      };
 
   return (
     <div className="bg-base-100 relative isolate min-h-screen overflow-hidden">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docubook/flame",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.",
   "type": "module",
   "bin": {
@@ -54,8 +54,8 @@
     "unified": "^11.0.0",
     "@docubook/core": "^1.8.0",
     "@docubook/mdx-content": "^3.4.0",
-    "@docubook/ui-react": "^0.1.4",
-    "@docubook/themes-colors": "^0.10.2"
+    "@docubook/themes-colors": "^0.10.2",
+    "@docubook/ui-react": "^0.1.4"
   },
   "peerDependencies": {
     "@sentry/bun": "^10.0.0"