boltdocs 3.2.1 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boltdocs",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "A lightweight documentation generator for React projects.",
   "main": "dist/node/index.mjs",
   "module": "dist/node/index.mjs",
@@ -42,6 +42,11 @@
       "import": "./dist/client/index.js",
       "require": "./dist/client/index.cjs"
     },
+    "./client/router": {
+      "types": "./dist/client/router.d.ts",
+      "import": "./dist/client/router.js",
+      "require": "./dist/client/router.cjs"
+    },
     "./primitives": {
       "types": "./dist/client/primitives.d.ts",
       "import": "./dist/client/primitives.js",
@@ -74,8 +79,7 @@
   "author": "Jesus Alcala",
   "license": "MIT",
   "dependencies": {
-    "@bdocs/dui": "^0.3.0",
-    "@mdx-js/rollup": "3.1.1",
+    "@bdocs/dui": "^0.6.0",
     "@shikijs/engine-oniguruma": "3.23.0",
     "@shikijs/langs": "3.23.0",
     "@shikijs/themes": "3.23.0",
@@ -88,28 +92,26 @@
     "flexsearch": "0.8.212",
     "github-slugger": "2.0.0",
     "isomorphic-dompurify": "3.7.1",
+    "jiti": "^2.7.0",
     "lru-cache": "^11.3.6",
     "picomatch": "^4.0.4",
-    "semver": "^7.7.4",
     "react-helmet-async": "^2.0.1",
-    "react-router-dom": "^7.0.0",
-    "rehype-slug": "6.0.0",
-    "remark-frontmatter": "5.0.0",
-    "remark-gfm": "4.0.1",
     "scroll-into-view-if-needed": "3.1.0",
+    "semver": "^7.7.4",
     "shiki": "3.23.0",
     "tailwind-merge": "3.5.0",
-    "vite": "7.0.0 || 8.0.0",
+    "vite": "8.1.5",
     "zod": "4.3.6",
-    "@bdocs/parser": "1.1.0",
-    "@bdocs/plugin-image-optimizer": "0.2.1",
-    "@bdocs/ssg": "0.3.0",
-    "@bdocs/unist-utils": "0.2.0"
+    "@bdocs/parser": "1.2.0",
+    "@bdocs/plugin-image-optimizer": "0.2.2",
+    "@bdocs/unist-utils": "0.2.0",
+    "@bdocs/ssg": "0.4.0",
+    "@bdocs/processor-satteri": "0.3.0"
   },
   "peerDependencies": {
     "react": "19.0.0",
-    "react-dom": "19.0.0",
-    "react-aria-components": "^1.16.0"
+    "react-aria-components": "^1.16.0",
+    "react-dom": "19.0.0"
   },
   "devDependencies": {
     "@netlify/functions": "^5.3.0",
@@ -128,7 +130,7 @@
     "tsdown": "0.21.7",
     "typescript": "5.9.3",
     "vitest": "^3.0.0",
-    "@bdocs/processor-satteri": "0.2.0"
+    "tsdown-config": "1.0.0"
   },
   "scripts": {
     "build": "tsdown --config-loader unrun",

package/src/shared/mdx-path.ts

@@ -0,0 +1,12 @@
+export function normalizeMdxPath(value: string): string {
+  return value.replace(/\\/g, '/').replace(/^\/+/, '')
+}
+
+export function matchesMdxUpdatePath(
+  routeFilePath: string,
+  updateRelativePath: string,
+): boolean {
+  return (
+    normalizeMdxPath(routeFilePath) === normalizeMdxPath(updateRelativePath)
+  )
+}

package/src/shared/structured-data.ts

@@ -0,0 +1,145 @@
+import type { JsonLdObject, StructuredData } from './types'
+
+export interface WebSiteStructuredDataOptions {
+  name: string
+  url: string
+  description?: string
+  searchUrl?: string
+}
+
+export interface ArticleStructuredDataOptions {
+  headline: string
+  url: string
+  description?: string
+  datePublished?: string | Date
+  dateModified?: string | Date
+  image?: string
+  author?: string | { name: string; url?: string }
+}
+
+export interface BreadcrumbStructuredDataItem {
+  name: string
+  url: string
+}
+
+export interface StructuredDataFactoryOptions {
+  /** A WebSite graph for the global site identity. */
+  website?: WebSiteStructuredDataOptions
+  /** An Article graph for the current page or release post. */
+  article?: ArticleStructuredDataOptions
+  /** A BreadcrumbList graph for the current page hierarchy. */
+  breadcrumbs?: BreadcrumbStructuredDataItem[]
+  /** Additional graph nodes for schema types not covered by the presets. */
+  additional?: JsonLdObject | JsonLdObject[]
+}
+
+/** Preserve literal JSON-LD types in config files and frontmatter helpers. */
+export function defineStructuredData<T extends StructuredData>(data: T): T {
+  return data
+}
+
+/**
+ * Creates one JSON-LD value from the common website/article/breadcrumb presets.
+ * Single-node input returns an object; multiple nodes return a graph array.
+ */
+export function createStructuredData(
+  options: StructuredDataFactoryOptions,
+): StructuredData {
+  const nodes: JsonLdObject[] = []
+
+  if (options.website) {
+    nodes.push(createWebSiteStructuredData(options.website))
+  }
+  if (options.article) {
+    nodes.push(createArticleStructuredData(options.article))
+  }
+  if (options.breadcrumbs?.length) {
+    nodes.push(createBreadcrumbStructuredData(options.breadcrumbs))
+  }
+  if (options.additional) {
+    nodes.push(
+      ...(Array.isArray(options.additional)
+        ? options.additional
+        : [options.additional]),
+    )
+  }
+
+  if (nodes.length === 0) {
+    throw new Error(
+      'createStructuredData() requires at least one of website, article, breadcrumbs, or additional',
+    )
+  }
+
+  return nodes.length === 1 ? nodes[0] : nodes
+}
+
+export function createWebSiteStructuredData(
+  options: WebSiteStructuredDataOptions,
+): JsonLdObject {
+  const data: JsonLdObject = {
+    '@context': 'https://schema.org',
+    '@type': 'WebSite',
+    name: options.name,
+    url: options.url,
+  }
+
+  if (options.description) data.description = options.description
+  if (options.searchUrl) {
+    data.potentialAction = {
+      '@type': 'SearchAction',
+      target: `${options.searchUrl}{search_term_string}`,
+      'query-input': 'required name=search_term_string',
+    }
+  }
+
+  return data
+}
+
+function toIsoDate(value: string | Date, field: string): string {
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) {
+    throw new TypeError(`Invalid ${field} value: ${String(value)}`)
+  }
+  return date.toISOString()
+}
+
+export function createArticleStructuredData(
+  options: ArticleStructuredDataOptions,
+): JsonLdObject {
+  const data: JsonLdObject = {
+    '@context': 'https://schema.org',
+    '@type': 'Article',
+    headline: options.headline,
+    url: options.url,
+  }
+
+  if (options.description) data.description = options.description
+  if (options.datePublished)
+    data.datePublished = toIsoDate(options.datePublished, 'datePublished')
+  if (options.dateModified)
+    data.dateModified = toIsoDate(options.dateModified, 'dateModified')
+  if (options.image) data.image = options.image
+  if (options.author) {
+    data.author =
+      typeof options.author === 'string'
+        ? { '@type': 'Person', name: options.author }
+        : { '@type': 'Person', ...options.author }
+  }
+
+  return data
+}
+
+export function createBreadcrumbStructuredData(
+  items: BreadcrumbStructuredDataItem[],
+): JsonLdObject {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: items.map((item, index) => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: item.name,
+      item: item.url,
+    })),
+  }
+}

package/src/shared/types.ts

@@ -1,4 +1,4 @@
-import type { Plugin as VitePlugin } from 'vite'
+import type { AliasOptions, Plugin as VitePlugin, UserConfig } from 'vite'
 import type { ComponentType } from 'react'
 
 /**
@@ -59,7 +59,7 @@ export interface RouteMeta {
   /** The raw markdown content of the page */
   _rawContent?: string
   /** Extracted SEO and Open Graph metadata from frontmatter */
-  seo?: Record<string, any>
+  seo?: Record<string, unknown>
   /** The publication date */
   date?: string | Date
   /** The last updated timestamp or date */
@@ -73,7 +73,7 @@ export interface RouteMeta {
   /** Whether the page is hidden from the sidebar */
   sidebarHidden?: boolean
   /** Raw extensible frontmatter data for custom components and formatters */
-  frontmatter?: Record<string, any>
+  frontmatter?: Record<string, unknown>
   /** Optional recursive child routes for deep sidebar hierarchies */
   subRoutes?: RouteMeta[]
   /** Clean URL segments stripped of locale/version prefixes */
@@ -580,15 +580,153 @@ export type PluginServerMiddleware = (
   next: (err?: unknown) => void,
 ) => void | Promise<void>
 
+/**
+ * Public API surface of the core plugin lifecycle manager.
+ *
+ * This is exposed as an interface so that plugin authors and internal
+ * subsystems can receive a reference to the lifecycle manager without
+ * pulling in the concrete class (which has private members and is not
+ * stable across source/dist boundaries during development).
+ */
+export interface IPluginLifecycleManager {
+  runHook(
+    hookName: keyof PluginLifecycleHooks,
+    ...args: unknown[]
+  ): Promise<void>
+  runChain<TParams extends Record<string, unknown>>(
+    hookName: keyof PluginLifecycleHooks,
+    initialParams: TParams,
+  ): Promise<TParams>
+  runMiddlewareChain<TParams extends Record<string, unknown>>(
+    hookName: 'transformSource' | 'transformMdx' | 'transformHtml',
+    initialParams: TParams,
+  ): Promise<TParams>
+  hasHook(
+    hookName:
+      | keyof PluginLifecycleHooks
+      | 'transformSource'
+      | 'transformMdx'
+      | 'transformHtml',
+  ): boolean
+}
+
+/**
+ * Standardized Search Document contract passed to search plugins.
+ */
+export interface SearchDocument {
+  id: string
+  path: string
+  title: string
+  content: string
+  headings: Array<{ level: number; text: string; id: string }>
+  frontmatter: Record<string, unknown>
+  locale?: string
+  version?: string
+}
+
+/**
+ * Agnostic UI slots for component injection.
+ */
+export type BoltdocsUiSlot =
+  | 'search:dialog'
+  | 'header:left'
+  | 'header:right'
+  | 'sidebar:top'
+  | 'sidebar:bottom'
+  | 'page:before'
+  | 'page:after'
+  | (string & {})
+
+export interface PluginHeadEntry {
+  tag: 'script' | 'link' | 'meta' | 'style'
+  attrs?: Record<string, string | boolean>
+  content?: string
+}
+
+/**
+ * Client-side configuration and UI slot injections for plugins.
+ */
+export interface PluginClientConfig {
+  /** Dynamic UI slot registrations (mapped to component file paths) */
+  slots?: Record<string, string>
+  /** Top-level React provider component file paths */
+  providers?: string[]
+  /** MDX component overrides & additions */
+  mdxComponents?: Record<string, string>
+  /** Head elements to inject into rendered HTML */
+  head?: PluginHeadEntry[]
+}
+
 /**
  * Plugin lifecycle hooks with full type safety.
  */
 export interface PluginLifecycleHooks {
+  /** Build hooks (Astro-style) */
+  'build:before'?: (ctx: PluginContext) => Promise<void> | void
+  'build:after'?: (ctx: PluginContext) => Promise<void> | void
+  'build:end'?: (ctx: PluginContext) => Promise<void> | void
+  'build:generate'?: (
+    ctx: PluginContext,
+    params: { routes: RouteMeta[]; outDir: string; siteUrl?: string },
+  ) => void | Promise<void>
+
+  /** Dev hooks (Astro-style) */
+  'dev:before'?: (ctx: PluginContext) => Promise<void> | void
+  'dev:after'?: (ctx: PluginContext) => Promise<void> | void
+
+  /** Transform hooks (Astro-style) */
+  'transform:source'?: (
+    ctx: PluginContext,
+    params: TransformSourceParams,
+  ) =>
+    | TransformResult<{ code: string }>
+    | Promise<TransformResult<{ code: string }>>
+  'transform:mdx'?: (
+    ctx: PluginContext,
+    params: TransformSourceParams,
+  ) =>
+    | TransformResult<{ code: string }>
+    | Promise<TransformResult<{ code: string }>>
+  'transform:html'?: (
+    ctx: PluginContext,
+    params: TransformHtmlParams,
+  ) =>
+    | TransformResult<{ html: string }>
+    | Promise<TransformResult<{ html: string }>>
+
+  /** Dynamic frontmatter transformation hook */
+  'frontmatter:transform'?: (
+    ctx: PluginContext,
+    params: {
+      frontmatter: Record<string, unknown>
+      filePath: string
+      rawContent: string
+    },
+  ) => Record<string, unknown> | Promise<Record<string, unknown>> | undefined
+
+  /** Fired after routes are crawled, normalized, and resolved */
+  'routes:resolved'?: (
+    ctx: PluginContext,
+    params: { routes: RouteMeta[] },
+  ) => RouteMeta[] | Promise<RouteMeta[]> | undefined
+
+  /** Agnostic search index hook: core passes SearchDocument[], plugin returns index payload */
+  'search:index'?: (
+    ctx: PluginContext,
+    params: { documents: SearchDocument[]; routes: RouteMeta[] },
+  ) => unknown | Promise<unknown>
+
+  'server:configure'?: (
+    ctx: PluginContext,
+    params: { server: unknown; middleware: PluginServerAPI },
+  ) => void | Promise<void>
+
+  /** Legacy alias hooks for backwards compatibility */
   beforeBuild?: (ctx: PluginContext) => Promise<void> | void
   afterBuild?: (ctx: PluginContext) => Promise<void> | void
+  buildEnd?: (ctx: PluginContext) => Promise<void> | void
   beforeDev?: (ctx: PluginContext) => Promise<void> | void
   afterDev?: (ctx: PluginContext) => Promise<void> | void
-  buildEnd?: (ctx: PluginContext) => Promise<void> | void
   transformSource?: (
     ctx: PluginContext,
     params: TransformSourceParams,
@@ -614,15 +752,22 @@ export interface PluginLifecycleHooks {
  * When `processor` is set to 'satteri', the Sätteri Rust-based compiler is used.
  */
 export interface BoltdocsMdxConfig {
-  processor?: 'unified' | 'satteri'
+  processor?: 'satteri'
 }
 
 /**
  * Defines a Boltdocs plugin.
  *
- * Use the `createPlugin()` helper from the node API for full type safety and
- * access to lifecycle hooks.
+ * Use the `definePlugin()` or `createPlugin()` helper from the node API for full
+ * type safety and access to lifecycle hooks.
  */
+export interface PluginCssConfig {
+  cssFiles?: string[]
+  headStyles?: string[]
+  postcssPlugins?: unknown[]
+  preprocessorOptions?: Record<string, unknown>
+}
+
 export interface BoltdocsPlugin {
   name: string
   enforce?: 'pre' | 'post'
@@ -632,11 +777,10 @@ export interface BoltdocsPlugin {
   rehypePlugins?: unknown[]
   vitePlugins?: VitePlugin[]
   components?: Record<string, string>
-  /** Optional runtime metadata exposed to client via useConfig().plugins[].metadata */
+  client?: PluginClientConfig
   metadata?: Record<string, unknown>
-  /** Declarative transform middleware entries. */
+  css?: PluginCssConfig
   middleware?: PluginTransformMiddleware[]
-  /** Lifecycle hooks with full type safety */
   hooks?: PluginLifecycleHooks
 }
 
@@ -666,6 +810,13 @@ export interface BoltdocsVerificationConfig {
 /**
  * Configuration for SEO.
  */
+export type JsonLdPrimitive = string | number | boolean | null
+export type JsonLdValue = JsonLdPrimitive | JsonLdObject | JsonLdValue[]
+export interface JsonLdObject {
+  [key: string]: JsonLdValue | undefined
+}
+export type StructuredData = JsonLdObject | JsonLdObject[]
+
 export interface BoltdocsSeoConfig {
   metatags?: Record<string, string>
   indexing?: 'all' | 'public'
@@ -673,6 +824,37 @@ export interface BoltdocsSeoConfig {
     background?: string
   }
   verification?: BoltdocsVerificationConfig
+  /** Global JSON-LD graph emitted in every page head. */
+  structuredData?: StructuredData
+}
+
+export interface BoltdocsViewTransitionsConfig {
+  /** Native document transitions are enabled when true. */
+  enabled?: boolean
+  /** Optional transition types passed to `document.startViewTransition`. */
+  types?: string[]
+}
+
+export interface BoltdocsExperimentalConfig {
+  /** Enables the native View Transition API integration. */
+  viewTransitions?: boolean | BoltdocsViewTransitionsConfig
+  /** Enables static file-routing under `docs/pages-external/`. */
+  fileRouting?: boolean
+}
+
+export type ExperimentalViewTransitions =
+  | boolean
+  | BoltdocsViewTransitionsConfig
+
+export interface ExternalFileRoute {
+  path: string
+  filePath: string
+  kind: 'component' | 'mdx'
+  /**
+   * Locale the file provides, derived from a `pages-external/{locale}/`
+   * directory. Absent for default-locale files.
+   */
+  locale?: string
 }
 
 /**
@@ -770,6 +952,14 @@ export interface BoltdocsIntegrationsConfig {
   }
 }
 
+/**
+ * Configuration for static site generation.
+ */
+export interface BoltdocsSsgConfig {
+  /** Critical CSS strategy; `none` disables critical CSS processing. */
+  criticalCss?: 'zig-critters' | 'beasties' | 'none'
+}
+
 /**
  * Configuration for drafts visibility control.
  */
@@ -791,6 +981,7 @@ export interface BoltdocsConfig {
   i18n?: BoltdocsI18nConfig
   versions?: BoltdocsVersionsConfig
   mdx?: BoltdocsMdxConfig
+  ssg?: BoltdocsSsgConfig
   plugins?: BoltdocsPlugin[]
   collections?: BoltdocsCollectionsConfig
   robots?: BoltdocsRobotsConfig
@@ -799,8 +990,10 @@ export interface BoltdocsConfig {
   integrations?: BoltdocsIntegrationsConfig
   drafts?: BoltdocsDraftsConfig
   featureFlags?: Record<string, boolean | string>
+  experimental?: BoltdocsExperimentalConfig
   directoryMeta?: Record<string, unknown>
-  vite?: unknown
+  aliases?: AliasOptions
+  vite?: UserConfig
 }
 
 /**
@@ -824,9 +1017,20 @@ export type BoltdocsTypes = Boltdocs.Types
 
 export type BoltdocsRoutePath = keyof Boltdocs.RoutePaths
 
-export type BoltdocsRoutePathWithFallback = BoltdocsRoutePath extends never
-  ? string
-  : BoltdocsRoutePath
+export type ExternalRouteReference =
+  | `/${string}`
+  | `#${string}`
+  | `?${string}`
+  | `site:/${string}`
+  | `site:${string}`
+  | `http://${string}`
+  | `https://${string}`
+  | `//${string}`
+
+export type BoltdocsRoutePathWithFallback =
+  | BoltdocsRoutePath
+  | ExternalRouteReference
+  | string
 
 export type BoltdocsLocale = Boltdocs.Types extends { Locale: infer L }
   ? L
@@ -849,6 +1053,6 @@ export type BoltdocsMdxComponents = Boltdocs.Types extends {
   MdxComponents: infer M
 }
   ? TransformMdxComponents<UnpackMdxComponents<M>>
-  : Omit<Record<string, ComponentType<any>>, 'Frontmatter'> & {
-      Frontmatter: Record<string, ComponentType<any>>
+  : Omit<Record<string, ComponentType<unknown>>, 'Frontmatter'> & {
+      Frontmatter: Record<string, ComponentType<unknown>>
     }

package/dist/banner-BMop1KLF.d.ts

@@ -1,100 +0,0 @@
-
-import { T as BoltdocsConfig, a as SidebarItem, d as SidebarMobile, f as SidebarRoot, i as SidebarHeader, l as SidebarLink, n as SidebarContent, p as SidebarSubGroup, r as SidebarGroup, s as SidebarItems, v as ComponentRoute, x as OnThisPageProps } from "./sidebar-COTaMHR-.js";
-import { ReactNode } from "react";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
-
-//#region src/client/components/ui-base/navbar.d.ts
-declare function Navbar(): _$react_jsx_runtime0.JSX.Element;
-//#endregion
-//#region src/client/components/ui-base/sidebar.d.ts
-interface SidebarProps {
-  routes: ComponentRoute[];
-  config: BoltdocsConfig;
-}
-declare function SidebarMain({
-  routes,
-  config
-}: SidebarProps): _$react_jsx_runtime0.JSX.Element;
-declare const Sidebar: typeof SidebarMain & {
-  Root: typeof SidebarRoot;
-  Mobile: typeof SidebarMobile;
-  Header: typeof SidebarHeader;
-  Content: typeof SidebarContent;
-  Group: typeof SidebarGroup;
-  Link: typeof SidebarLink;
-  SubGroup: typeof SidebarSubGroup;
-  Item: typeof SidebarItem;
-  Items: typeof SidebarItems;
-};
-//#endregion
-//#region src/client/components/ui-base/on-this-page.d.ts
-declare function OnThisPage({
-  headings,
-  editLink,
-  communityHelp,
-  filePath
-}: OnThisPageProps): _$react_jsx_runtime0.JSX.Element;
-//#endregion
-//#region src/client/components/ui-base/breadcrumbs.d.ts
-declare function Breadcrumbs(): _$react_jsx_runtime0.JSX.Element | null;
-//#endregion
-//#region src/client/components/ui-base/page-nav.d.ts
-/**
- * Component to display the previous and next page navigation buttons.
- * Enhanced with subtle entrance animations, modern card layout, and hover highlights.
- */
-declare function PageNav(): _$react_jsx_runtime0.JSX.Element | null;
-//#endregion
-//#region src/client/components/ui-base/error-boundary.d.ts
-interface ErrorBoundaryProps {
-  children?: ReactNode;
-  fallback?: ReactNode;
-}
-declare function ErrorBoundary({
-  children,
-  fallback
-}: ErrorBoundaryProps): _$react_jsx_runtime0.JSX.Element;
-//#endregion
-//#region src/client/components/ui-base/copy-markdown.d.ts
-interface CopyMarkdownProps {
-  content?: string;
-  mdxRaw?: string;
-  route?: ComponentRoute;
-}
-declare function CopyMarkdown({
-  content,
-  mdxRaw
-}: CopyMarkdownProps): _$react_jsx_runtime0.JSX.Element | null;
-//#endregion
-//#region src/client/components/ui-base/search-dialog.d.ts
-declare function SearchDialog({
-  routes
-}: {
-  routes: ComponentRoute[];
-}): _$react_jsx_runtime0.JSX.Element;
-//#endregion
-//#region src/client/components/ui-base/not-found.d.ts
-declare function NotFound(): _$react_jsx_runtime0.JSX.Element;
-//#endregion
-//#region src/client/components/ui-base/banner.d.ts
-interface BannerProps extends React.HTMLAttributes<HTMLDivElement> {
-  /**
-   * If true, shows a close button to dismiss the banner.
-   */
-  dismissible?: boolean;
-  /**
-   * Unique identifier for the banner. If provided and dismissible is true,
-   * the dismissed state will be saved in localStorage so it doesn't reappear
-   * on subsequent visits.
-   */
-  id?: string;
-}
-declare function Banner({
-  children,
-  className,
-  dismissible,
-  id,
-  ...props
-}: BannerProps): _$react_jsx_runtime0.JSX.Element | null;
-//#endregion
-export { ErrorBoundary as a, OnThisPage as c, CopyMarkdown as i, Sidebar as l, NotFound as n, PageNav as o, SearchDialog as r, Breadcrumbs as s, Banner as t, Navbar as u };