ardo 3.2.1 → 3.4.0

package/README.md

@@ -1,10 +1,18 @@
 # ardo
 
-React-first Static Documentation Framework built on React Router 7.
+Modern, open documentation for React teams.
 
-## Quick Start
+Ardo is a React-first static documentation framework built on React 19, React Router 7, Vite 8, MDX, TypeScript, and Vanilla Extract. It is for teams that want VitePress-style simplicity without leaving React or moving their docs into a hosted platform.
 
-Scaffold a new project with the CLI:
+## Why use it?
+
+- **Use real React components in docs** - import your app components, design system, providers, and examples directly in MDX.
+- **Ship static docs anywhere** - Ardo prerenders HTML and assets that work on GitHub Pages, Vercel, Netlify, Cloudflare Pages, or any file server.
+- **Generate API docs from TypeScript** - TypeDoc integration creates linked API reference pages during build.
+- **Start with a complete theme** - responsive layout, sidebar, TOC, search, dark mode, code highlighting, callouts, tabs, Tailwind v4, and typed design tokens.
+- **Keep control** - configuration is code, UI is React, output is static, and the package is open source.
+
+## Quick start
 
 ```bash
 pnpm create ardo@latest my-docs
@@ -13,80 +21,80 @@ pnpm install
 pnpm dev
 ```
 
-## Manual Installation
+## Manual installation
 
 ```bash
-pnpm add ardo react react-dom react-router
-pnpm add -D typescript vite
+pnpm add ardo react react-dom react-router isbot
+pnpm add -D @react-router/dev @tailwindcss/vite tailwindcss typescript vite @types/react @types/react-dom
 ```
 
-## Usage
-
-### Vite Configuration
-
-Create a `vite.config.ts` with your Ardo configuration:
+## Vite configuration
 
-```typescript
+```ts
 import { defineConfig } from "vite"
+import tailwindcss from "@tailwindcss/vite"
 import { ardo } from "ardo/vite"
 
 export default defineConfig({
   plugins: [
+    tailwindcss(),
     ardo({
       title: "My Documentation",
-      description: "Built with Ardo",
+      description: "Docs for my React library",
     }),
   ],
 })
 ```
 
-The `ardo()` plugin includes React Router, MDX processing, and all necessary configuration. Navigation, sidebar, footer, and other UI configuration is done via JSX props in your `root.tsx`.
+The `ardo()` plugin handles build-time behavior: route generation, MDX processing, TypeDoc generation, search data, and static build metadata. UI configuration stays in React through `ArdoRoot` and component props.
 
-### Runtime Hooks
+Ardo also generates the modern lean favicon set (`favicon.ico`, `icon.svg`, and `apple-touch-icon.png`) from the default Ardo mark. Use `icons: { source: "./app/assets/logo.svg" }` to generate those files from your own SVG, or `icons: false` to manage them from `public/`.
 
-Access configuration and page data in your components:
+## Root layout
 
 ```tsx
-import { useArdoConfig, useArdoSidebar, useArdoPageData, useArdoTOC } from "ardo/runtime"
+import { ArdoRoot, ArdoRootLayout } from "ardo/ui"
+import config from "virtual:ardo/config"
+import sidebar from "virtual:ardo/sidebar"
+import "ardo/ui/styles.css"
 
-function MyComponent() {
-  const config = useArdoConfig()
-  const sidebar = useArdoSidebar()
-  const page = useArdoPageData()
-  const toc = useArdoTOC()
+export function Layout({ children }: { children: React.ReactNode }) {
+  return <ArdoRootLayout>{children}</ArdoRootLayout>
+}
 
-  return <h1>{config.title}</h1>
+export default function Root() {
+  return <ArdoRoot config={config} sidebar={sidebar} />
 }
 ```
 
-### Theme Components
-
-Use pre-built components for your documentation:
+## Runtime hooks
 
 ```tsx
-import { ArdoLayout, ArdoHeader, ArdoSidebar, ArdoFooter } from "ardo/ui"
-
-function App() {
-  return (
-    <ArdoLayout header={<ArdoHeader />} sidebar={<ArdoSidebar />} footer={<ArdoFooter />}>
-      <YourContent />
-    </ArdoLayout>
-  )
+import { useArdoConfig, useArdoPageData, useArdoSidebar, useArdoTOC } from "ardo/runtime"
+
+function PageTitle() {
+  const config = useArdoConfig()
+  const page = useArdoPageData()
+  const sidebar = useArdoSidebar()
+  const toc = useArdoTOC()
+
+  return <h1>{page?.title ?? config.title}</h1>
 }
 ```
 
 ## Exports
 
-| Export               | Description               |
-| -------------------- | ------------------------- |
-| `ardo/vite`          | Vite plugin (`ardo`)      |
-| `ardo/runtime`       | React hooks and providers |
-| `ardo/ui`            | Pre-built UI components   |
-| `ardo/ui/styles.css` | Default theme styles      |
+| Export               | Description                        |
+| -------------------- | ---------------------------------- |
+| `ardo/vite`          | Vite plugin                        |
+| `ardo/runtime`       | React hooks and providers          |
+| `ardo/ui`            | Default UI components              |
+| `ardo/theme`         | Vanilla Extract tokens and theming |
+| `ardo/ui/styles.css` | Default theme styles               |
 
 ## Documentation
 
-Full documentation available at [ardo-docs.dev](https://ardo-docs.dev)
+Full documentation: [ardo-docs.dev](https://ardo-docs.dev)
 
 LLM-optimized documentation: [llms-full.txt](https://ardo-docs.dev/llms-full.txt)
 

package/dist/{DocPage-CIBiCAxZ.js → DocPage-Dy7OrCP2.js}

@@ -1,35 +1,38 @@
-import { d as useArdoSiteConfig, f as useArdoTOC, l as useArdoPageData, n as getPrevNextLinks, r as ArdoContext, u as useArdoSidebar } from "./sidebar-utils-1Skqle1Q.js";
+import { d as useArdoSidebar, f as useArdoSiteConfig, n as getPrevNextLinks, p as useArdoTOC, r as ArdoContext, s as useArdoConfig, u as useArdoPageData } from "./sidebar-utils-C06DJsx4.js";
+import { t as ARDO_FAVICON_DATA_URL } from "./favicon-Cx-inut3.js";
 import { Children, createContext, isValidElement, use, useEffect, useMemo, useRef, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { Link, Links, Meta, Scripts, ScrollRestoration, useLocation } from "react-router";
-import { Check as CheckIcon, ChevronDown as ChevronDownIcon, CircleX as XCircleIcon, Copy as CopyIcon, FileText as FileTextIcon, Info as InfoIcon, Lightbulb as LightbulbIcon, MessageCircle as MessageCircleIcon, Monitor as MonitorIcon, Moon as MoonIcon, Search as SearchIcon, Sun as SunIcon, TriangleAlert as AlertTriangleIcon, X as XIcon } from "lucide-react";
-import "./assets/src/ui/Footer.css.ts.vanilla-BSzPIPt4.css";
-import "./assets/src/ui/Layout.css.ts.vanilla-Bpx_-gJt.css";
-import "./assets/src/ui/components/CodeBlock.css.ts.vanilla-lNKqskjQ.css";
-import "./assets/src/ui/components/CopyButton.css.ts.vanilla-DZZ5jgTM.css";
+import "./assets/src/ui/Layout.css.ts.vanilla-ClOa1YZm.css";
+import "./assets/src/ui/Footer.css.ts.vanilla-DGTyff5Y.css";
+import { BookOpen as BookOpenIcon, Box as BoxIcon, Check as CheckIcon, ChevronDown as ChevronDownIcon, CircleX as XCircleIcon, Code2 as CodeIcon, Copy as CopyIcon, FileCode2 as FileCodeIcon, FileText as FileTextIcon, Info as InfoIcon, Lightbulb as LightbulbIcon, MessageCircle as MessageCircleIcon, Monitor as MonitorIcon, Moon as MoonIcon, Package as PackageIcon, Search as SearchIcon, Settings as SettingsIcon, Sun as SunIcon, TriangleAlert as AlertTriangleIcon, Wrench as WrenchIcon, X as XIcon } from "lucide-react";
+import "./assets/src/ui/components/CopyButton.css.ts.vanilla-CO2awD6S.css";
+import "./assets/src/ui/components/CodeBlock.css.ts.vanilla-BxDJ2gKc.css";
 import "./assets/src/ui/components/Container.css.ts.vanilla-CUhRUA9t.css";
 import { createRuntimeFn } from "@vanilla-extract/recipes/createRuntimeFn";
 import "./assets/src/ui/components/Steps.css.ts.vanilla-CisaxeNj.css";
 import "./assets/src/ui/components/Tabs.css.ts.vanilla-C4-vJSnf.css";
 import "./assets/src/ui/Breadcrumb.css.ts.vanilla-Dpgq-C_p.css";
-import "./assets/src/ui/content.css.ts.vanilla-O_RaSPXm.css";
-import "./assets/src/ui/DocPage.css.ts.vanilla-CXKuz4U-.css";
-import "./assets/src/ui/Toc.css.ts.vanilla-CYqcWgvD.css";
+import "./assets/src/ui/content.css.ts.vanilla-CJnrOQNh.css";
+import "./assets/src/ui/DocPage.css.ts.vanilla-CWL92vUE.css";
+import "./assets/src/ui/Toc.css.ts.vanilla-CQbpEdTg.css";
 //#region src/ui/Footer.css.ts
-var contentMeta = "_169q00b9";
+var contentMeta = "_169q00bb";
 var footer = "_169q00b0";
-var footerBuildTime = "_169q00b7";
+var footerArdoLink = "_169q00b5";
+var footerBuildTime = "_169q00b9";
 var footerContainer = "_169q00b1";
-var footerCopyright = "_169q00b6";
+var footerCopyright = "_169q00b8";
 var footerLink = "_169q00b4";
-var footerMessage = "_169q00b5";
+var footerMessage = "_169q00b7";
+var footerOwl = "_169q00b6";
 var footerPrimary = "_169q00b2";
 var footerSeparator = "_169q00b3";
-var nextLink = "_169q00be _169q00bc";
-var prevLink = "_169q00bc";
-var prevNext = "_169q00bb";
-var prevNextLabel = "_169q00bf";
-var prevNextTitle = "_169q00bg";
+var nextLink = "_169q00bg _169q00be";
+var prevLink = "_169q00be";
+var prevNext = "_169q00bd";
+var prevNextLabel = "_169q00bh";
+var prevNextTitle = "_169q00bi";
 //#endregion
 //#region src/ui/Layout.css.ts
 var home = "_8autjm3";
@@ -40,7 +43,6 @@ var main = "_8autjm2";
 var skipLink = "_8autjm5";
 //#endregion
 //#region src/ui/Layout.tsx
-const ARDO_FAVICON = "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20style%3D%22stroke-linecap%3Around%3Bstroke-linejoin%3Around%22%20viewBox%3D%220%200%20600%20600%22%3E%3Cdefs%3E%3Csymbol%20id%3D%22a%22%20overflow%3D%22visible%22%3E%3Cpath%20d%3D%22M300%20300%20151%20128l2%20178-41%2094h93c-35%2032-55%2068-63%20107m63-106%2095%2081m-32-96%2028%2088%22%2F%3E%3Cellipse%20cx%3D%22222%22%20cy%3D%22327%22%20fill%3D%22%2300655a%22%20rx%3D%2220%22%20ry%3D%2233%22%2F%3E%3Ccircle%20cx%3D%22227%22%20cy%3D%22324%22%20r%3D%2271%22%2F%3E%3C%2Fsymbol%3E%3C%2Fdefs%3E%3Cg%20fill%3D%22none%22%20stroke%3D%22%2300655a%22%20stroke-width%3D%2216%22%3E%3Cpath%20d%3D%22M155%20318c2-70%2066-126%20145-126s143%2056%20145%20126%22%2F%3E%3Ccircle%20cx%3D%22300%22%20cy%3D%22290%22%20r%3D%22270%22%2F%3E%3Cuse%20href%3D%22%23a%22%2F%3E%3Cuse%20href%3D%22%23a%22%20transform%3D%22matrix%28-1%200%200%201%20600%200%29%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E";
 /**
 * Default HTML shell for Ardo sites. Replaces the boilerplate `Layout` export
 * that every root.tsx must define for React Router.
@@ -57,10 +59,12 @@ const ARDO_FAVICON = "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3
 * export const Layout = (props) => <RootLayout favicon={logo} {...props} />
 * ```
 */
-function ArdoRootLayout({ children, favicon, lang }) {
+function ArdoRootLayout({ children, favicon, iconBasePath = "/", lang }) {
 	const context = use(ArdoContext);
+	const resolvedLang = lang ?? context?.config.lang ?? "en";
+	const iconBaseUrl = iconBasePath === false ? void 0 : normalizeIconBasePath(iconBasePath);
 	return /* @__PURE__ */ jsxs("html", {
-		lang: lang ?? context?.config.lang ?? "en",
+		lang: resolvedLang,
 		suppressHydrationWarning: true,
 		children: [/* @__PURE__ */ jsxs("head", { children: [
 			/* @__PURE__ */ jsx("meta", { charSet: "utf-8" }),
@@ -68,11 +72,26 @@ function ArdoRootLayout({ children, favicon, lang }) {
 				name: "viewport",
 				content: "width=device-width, initial-scale=1"
 			}),
-			/* @__PURE__ */ jsx("link", {
+			iconBaseUrl == null ? /* @__PURE__ */ jsx("link", {
 				rel: "icon",
 				type: "image/svg+xml",
-				href: favicon ?? ARDO_FAVICON
-			}),
+				href: favicon ?? ARDO_FAVICON_DATA_URL
+			}) : /* @__PURE__ */ jsxs(Fragment, { children: [
+				/* @__PURE__ */ jsx("link", {
+					rel: "icon",
+					href: `${iconBaseUrl}favicon.ico`,
+					sizes: "32x32"
+				}),
+				/* @__PURE__ */ jsx("link", {
+					rel: "icon",
+					href: favicon ?? `${iconBaseUrl}icon.svg`,
+					type: "image/svg+xml"
+				}),
+				/* @__PURE__ */ jsx("link", {
+					rel: "apple-touch-icon",
+					href: `${iconBaseUrl}apple-touch-icon.png`
+				})
+			] }),
 			/* @__PURE__ */ jsx(Meta, {}),
 			/* @__PURE__ */ jsx(Links, {})
 		] }), /* @__PURE__ */ jsxs("body", {
@@ -85,6 +104,10 @@ function ArdoRootLayout({ children, favicon, lang }) {
 		})]
 	});
 }
+function normalizeIconBasePath(basePath) {
+	if (basePath === "") return "/";
+	return `${basePath.endsWith("/") ? basePath.slice(0, -1) : basePath}/`;
+}
 /**
 * Layout component with explicit slot props.
 *
@@ -691,6 +714,7 @@ var contentContainer = "_1f1m4jr1";
 var contentHeader = "_1f1m4jr2";
 var contentTitle = "_1f1m4jr3";
 var docPage = "_1f1m4jr0";
+var pageRail = "_1f1m4jr6";
 //#endregion
 //#region src/ui/Content.tsx
 function resolveEditLink(input) {
@@ -719,7 +743,7 @@ function resolveLastUpdated(input) {
 		show
 	};
 }
-function ArdoContent({ children, editLink, lastUpdated }) {
+function ArdoContent({ children, editLink, lastUpdated, metaPlacement = "footer" }) {
 	const isBare = useBareContent();
 	const pageData = useArdoPageData();
 	const siteConfig = useArdoSiteConfig();
@@ -750,7 +774,7 @@ function ArdoContent({ children, editLink, lastUpdated }) {
 				className: `${contentBody} ${ardoContent}`,
 				children
 			}),
-			/* @__PURE__ */ jsx(ContentMeta, {
+			metaPlacement === "footer" && /* @__PURE__ */ jsx(ContentMeta, {
 				edit,
 				updated
 			}),
@@ -782,7 +806,7 @@ function ContentMeta({ edit, updated }) {
 			href: edit.href,
 			target: "_blank",
 			rel: "noopener noreferrer",
-			className: "_169q00ba",
+			className: "_169q00bc",
 			children: edit.text
 		}), updated.show && /* @__PURE__ */ jsxs("span", { children: [
 			updated.label,
@@ -963,8 +987,14 @@ function ArdoDocPage({ children, editLink, lastUpdated, tocLabel }) {
 		children: [/* @__PURE__ */ jsx(ArdoContent, {
 			editLink,
 			lastUpdated,
+			metaPlacement: "none",
 			children
-		}), !hideToc && /* @__PURE__ */ jsx(ArdoTOC, { label: tocLabel })]
+		}), /* @__PURE__ */ jsx(ArdoPageRail, {
+			editLink,
+			lastUpdated,
+			tocLabel,
+			hideToc
+		})]
 	}) });
 }
 /**
@@ -994,10 +1024,109 @@ function ArdoDocContent({ children, editLink, lastUpdated, tocLabel }) {
 		children: [/* @__PURE__ */ jsx(ArdoContent, {
 			editLink,
 			lastUpdated,
+			metaPlacement: "none",
 			children
-		}), !hideToc && /* @__PURE__ */ jsx(ArdoTOC, { label: tocLabel })]
+		}), /* @__PURE__ */ jsx(ArdoPageRail, {
+			editLink,
+			lastUpdated,
+			tocLabel,
+			hideToc
+		})]
+	});
+}
+function ArdoPageRail({ editLink, lastUpdated, tocLabel, hideToc = false }) {
+	const config = useArdoConfig();
+	const siteConfig = useArdoSiteConfig();
+	const pageData = useArdoPageData();
+	const version = config.project?.version ?? "";
+	const edit = resolveRailEditLink({
+		pageData,
+		editLink,
+		siteConfig
+	});
+	const updated = resolveRailLastUpdated({
+		pageData,
+		lastUpdated,
+		siteConfig
+	});
+	const hasMeta = edit.show || updated.show;
+	const hasVersion = version !== "";
+	if (!hasVersion && !hasMeta && hideToc) return null;
+	return /* @__PURE__ */ jsxs("aside", {
+		className: pageRail,
+		children: [
+			hasVersion && /* @__PURE__ */ jsxs("section", {
+				className: "_1f1m4jr7",
+				children: [/* @__PURE__ */ jsx("h2", {
+					className: "_1f1m4jr8",
+					children: "Version"
+				}), /* @__PURE__ */ jsx("select", {
+					className: "_1f1m4jrb",
+					defaultValue: version,
+					"aria-label": "Version",
+					children: /* @__PURE__ */ jsx("option", {
+						value: version,
+						children: version
+					})
+				})]
+			}),
+			hasMeta && /* @__PURE__ */ jsxs("section", {
+				className: "_1f1m4jr7",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "_1f1m4jr8",
+						children: "Page"
+					}),
+					edit.show && /* @__PURE__ */ jsx("a", {
+						href: edit.href,
+						target: "_blank",
+						rel: "noopener noreferrer",
+						className: "_1f1m4jra",
+						children: edit.text
+					}),
+					updated.show && /* @__PURE__ */ jsxs("p", {
+						className: "_1f1m4jr9",
+						children: [
+							updated.label,
+							": ",
+							updated.text
+						]
+					})
+				]
+			}),
+			!hideToc && /* @__PURE__ */ jsx("section", {
+				className: "_1f1m4jr7",
+				children: /* @__PURE__ */ jsx(ArdoTOC, { label: tocLabel })
+			})
+		]
 	});
 }
+function resolveRailEditLink({ pageData, editLink, siteConfig }) {
+	const resolved = editLink ?? siteConfig.editLink;
+	const pattern = resolved?.pattern ?? "";
+	const relativePath = pageData?.relativePath ?? "";
+	const show = pageData?.frontmatter.editLink !== false && pattern !== "" && pageData !== void 0;
+	return {
+		href: show ? pattern.replace(":path", relativePath) : void 0,
+		text: resolved?.text ?? "Edit this page",
+		show
+	};
+}
+function resolveRailLastUpdated({ pageData, lastUpdated, siteConfig }) {
+	const resolved = lastUpdated ?? siteConfig.lastUpdated;
+	const value = pageData?.lastUpdated;
+	const show = pageData?.frontmatter.lastUpdated !== false && resolved?.enabled === true && typeof value === "number";
+	const formatOptions = resolved?.formatOptions ?? {
+		year: "numeric",
+		month: "long",
+		day: "numeric"
+	};
+	return {
+		label: resolved?.text ?? "Last updated",
+		text: show ? new Date(value).toLocaleDateString(void 0, formatOptions) : void 0,
+		show
+	};
+}
 /**
 * @deprecated Use DocPage or DocContent instead
 */
@@ -1005,6 +1134,6 @@ function ArdoDocLayout({ content }) {
 	return /* @__PURE__ */ jsx(ArdoDocPage, { children: content });
 }
 //#endregion
-export { home as A, footerSeparator as B, ArdoCopyButton as C, ArdoBareContent as D, codeWrapper as E, footerContainer as F, SearchIcon as G, MessageCircleIcon as H, footerCopyright as I, SunIcon as K, footerLink as L, layout as M, footer as N, ArdoLayout as O, footerBuildTime as P, footerMessage as R, ArdoCodeGroup as S, codeTitle as T, MonitorIcon as U, ChevronDownIcon as V, MoonIcon as W, ArdoInfo as _, ArdoContent as a, ArdoWarning as b, ArdoTabPanel as c, ArdoSteps as d, ArdoIcon as f, ArdoDanger as g, ArdoContainer as h, ArdoTOC as i, homeMain as j, ArdoRootLayout as k, ArdoTabPanels as l, registerIcons as m, ArdoDocLayout as n, ArdoTab as o, getRegisteredIconNames as p, XIcon as q, ArdoDocPage as r, ArdoTabList as s, ArdoDocContent as t, ArdoTabs as u, ArdoNote as v, codeBlock as w, ArdoCodeBlock as x, ArdoTip as y, footerPrimary as z };
+export { footerLink as $, home as A, MonitorIcon as B, ArdoCopyButton as C, ArdoBareContent as D, codeWrapper as E, ChevronDownIcon as F, SunIcon as G, PackageIcon as H, CodeIcon as I, footer as J, WrenchIcon as K, FileCodeIcon as L, layout as M, BookOpenIcon as N, ArdoLayout as O, BoxIcon as P, footerCopyright as Q, FileTextIcon as R, ArdoCodeGroup as S, codeTitle as T, SearchIcon as U, MoonIcon as V, SettingsIcon as W, footerBuildTime as X, footerArdoLink as Y, footerContainer as Z, ArdoInfo as _, ArdoContent as a, ArdoWarning as b, ArdoTabPanel as c, ArdoSteps as d, footerMessage as et, ArdoIcon as f, ArdoDanger as g, ArdoContainer as h, ArdoTOC as i, homeMain as j, ArdoRootLayout as k, ArdoTabPanels as l, registerIcons as m, ArdoDocLayout as n, footerPrimary as nt, ArdoTab as o, getRegisteredIconNames as p, XIcon as q, ArdoDocPage as r, footerSeparator as rt, ArdoTabList as s, ArdoDocContent as t, footerOwl as tt, ArdoTabs as u, ArdoNote as v, codeBlock as w, ArdoCodeBlock as x, ArdoTip as y, MessageCircleIcon as z };
 
-//# sourceMappingURL=DocPage-CIBiCAxZ.js.map
+//# sourceMappingURL=DocPage-Dy7OrCP2.js.map