boltdocs 3.0.2 → 3.1.0

package/dist/{sidebar-BAKgJ-Er.d.ts → sidebar-DH2iPKXM.d.cts}

@@ -1,10 +1,92 @@
 
 import * as React$2 from "react";
 import { ComponentType, ReactNode } from "react";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 import { Plugin } from "vite";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/shared/types.d.ts
+/**
+ * Metadata representing a single documentation route.
+ * This information is used to build the client-side router and the sidebar navigation.
+ */
+interface RouteMeta {
+  /** The final URL path for the route (e.g., '/docs/guide/start') */
+  path: string;
+  /** The absolute filesystem path to the source markdown/mdx file */
+  componentPath: string;
+  /** The title of the page, usually extracted from frontmatter or the filename */
+  title: string;
+  /** The relative path from the docs directory, used for edit links */
+  filePath: string;
+  /** Optional description of the page (for SEO/meta tags) */
+  description?: string;
+  /** Optional explicit position for ordering in the sidebar */
+  sidebarPosition?: number;
+  /** The group (directory) this route belongs to */
+  group?: string;
+  /** The display title for the route's group */
+  groupTitle?: string;
+  /** Optional explicit position for ordering the group itself */
+  groupPosition?: number;
+  /** Optional icon for the route's group */
+  groupIcon?: string;
+  /** The sub-route group this route belongs to (from folders starting with _) */
+  subRouteGroup?: string;
+  /** Extracted markdown headings for search indexing */
+  headings?: {
+    level: number;
+    text: string;
+    id: string;
+  }[];
+  /** The locale this route belongs to, if i18n is configured */
+  locale?: string;
+  /** The version this route belongs to, if versioning is configured */
+  version?: string;
+  /** Optional badge to display next to the sidebar item (e.g., 'New', 'Experimental') */
+  badge?: BadgeValue;
+  /** Optional icon to display (Lucide icon name or raw SVG) */
+  icon?: string;
+  /** The tab this route belongs to, if tabs are configured */
+  tab?: string;
+  /** The collection this route belongs to (from [name] directories like [blog]) */
+  collection?: string;
+  /** Tags for blog posts or other taxonomy */
+  tags?: string[];
+  /** Author identifier for blog posts */
+  author?: string;
+  /** Draft flag — excluded from production builds */
+  draft?: boolean;
+  /** Feature flags required for this page to be visible */
+  featureFlags?: string[];
+  /** Short excerpt/summary for list displays */
+  excerpt?: string;
+  /** Cover image for blog posts */
+  coverImage?: string;
+  /** The extracted plain-text content of the page for search indexing */
+  _content?: string;
+  /** The raw markdown content of the page */
+  _rawContent?: string;
+  /** Extracted SEO and Open Graph metadata from frontmatter */
+  seo?: Record<string, any>;
+  /** The publication date */
+  date?: string | Date;
+  /** The last updated timestamp or date */
+  lastUpdated?: string | number | Date;
+  /** Optional category for the page */
+  category?: string;
+  /** Optional explicit order (alternative to sidebarPosition) */
+  order?: number;
+  /** Optional explicit label for the sidebar */
+  sidebarLabel?: string;
+  /** Whether the page is hidden from the sidebar */
+  sidebarHidden?: boolean;
+  /** Raw extensible frontmatter data for custom components and formatters */
+  frontmatter?: Record<string, any>;
+  /** Optional recursive child routes for deep sidebar hierarchies */
+  subRoutes?: RouteMeta[];
+  /** Clean URL segments stripped of locale/version prefixes */
+  slugParts?: string[];
+}
 /**
  * Represents a single social link in the configuration.
  */
@@ -12,12 +94,6 @@ interface BoltdocsSocialLink {
   icon: 'discord' | 'x' | 'github' | 'bluesky' | string;
   link: string;
 }
-/**
- * Configuration for the site footer.
- */
-interface BoltdocsFooterConfig {
-  text?: string;
-}
 /**
  * Theme-specific configuration options.
  */
@@ -48,7 +124,6 @@ interface BoltdocsThemeConfig {
     icon?: string;
   }>;
   socialLinks?: BoltdocsSocialLink[];
-  footer?: BoltdocsFooterConfig;
   editLink?: string;
   communityHelp?: string;
   version?: string;
@@ -118,6 +193,85 @@ type BadgeValue = string | {
   text: string;
   expires?: string;
 };
+/**
+ * Context provided to plugin lifecycle hooks.
+ */
+interface PluginContext {
+  readonly config: BoltdocsConfig$1;
+  readonly logger: PluginLogger;
+  readonly store: PluginStore;
+  readonly meta: PluginMeta;
+  readonly docsDir: string;
+  readonly rootDir: string;
+  readonly outDir: string;
+  readonly routes: RouteMeta[];
+}
+/**
+ * Logger interface for plugin logging.
+ */
+interface PluginLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string | Error): void;
+  debug(message: string): void;
+}
+/**
+ * Key-value store interface for plugins.
+ */
+interface PluginStore {
+  get<T = unknown>(pluginName: string, key: string): T | undefined;
+  set(pluginName: string, key: string, value: unknown): void;
+  has(pluginName: string, key: string): boolean;
+}
+/**
+ * Plugin metadata provided in the context.
+ */
+interface PluginMeta {
+  name: string;
+  version?: string;
+  boltdocsVersion?: string;
+}
+/**
+ * Plugin lifecycle hooks with full type safety.
+ */
+interface PluginLifecycleHooks {
+  beforeBuild?: (ctx: PluginContext) => Promise<void> | void;
+  afterBuild?: (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: {
+    code: string;
+    filePath: string;
+  }) => Promise<{
+    code: string;
+  }> | {
+    code: string;
+  };
+  transformMdx?: (ctx: PluginContext, params: {
+    code: string;
+    filePath: string;
+  }) => Promise<{
+    code: string;
+  }> | {
+    code: string;
+  };
+  transformHtml?: (ctx: PluginContext, params: {
+    html: string;
+    path: string;
+  }) => Promise<{
+    html: string;
+  }> | {
+    html: string;
+  };
+}
+/**
+ * MDX processor configuration.
+ * When `processor` is set to 'satteri', the Sätteri Rust-based compiler is used.
+ */
+interface BoltdocsMdxConfig {
+  processor?: 'unified' | 'satteri';
+}
 /**
  * Defines a Boltdocs plugin.
  *
@@ -133,8 +287,8 @@ interface BoltdocsPlugin {
   rehypePlugins?: unknown[];
   vitePlugins?: Plugin[];
   components?: Record<string, string>;
-  /** Lifecycle hooks — use the `PluginLifecycleHooks` type from the node API. */
-  hooks?: Record<string, (ctx: unknown) => Promise<void> | void>;
+  /** Lifecycle hooks with full type safety */
+  hooks?: PluginLifecycleHooks;
 }
 /**
  * Configuration for the collections (blog) feature.
@@ -236,11 +390,20 @@ interface BoltdocsVercelConfig {
   analytics?: boolean;
   speedInsights?: boolean;
 }
+interface BoltdocsPostHogConfig {
+  apiKey: string;
+  host?: string;
+  capturePageview?: boolean;
+  capturePageleave?: boolean;
+  sessionRecording?: boolean;
+  autocapture?: boolean;
+}
 interface BoltdocsIntegrationsConfig {
   analytics?: {
     ga4?: BoltdocsGA4Config;
     vercel?: BoltdocsVercelConfig;
     gtm?: BoltdocsGTMConfig;
+    posthog?: BoltdocsPostHogConfig;
   };
   search?: {
     algolia?: BoltdocsAlgoliaConfig;
@@ -250,6 +413,15 @@ interface BoltdocsIntegrationsConfig {
     custom?: BoltdocsCustomFeedbackConfig;
   };
 }
+/**
+ * Configuration for drafts visibility control.
+ */
+interface BoltdocsDraftsConfig {
+  /** If true, drafts are visible in all environments. Default: false */
+  visible?: boolean;
+  /** Environments where drafts are visible (e.g. ['development', 'staging']). Default: [] */
+  environments?: string[];
+}
 /**
  * The root configuration object for Boltdocs.
  */
@@ -260,12 +432,15 @@ interface BoltdocsConfig$1 {
   theme?: BoltdocsThemeConfig;
   i18n?: BoltdocsI18nConfig;
   versions?: BoltdocsVersionsConfig;
+  mdx?: BoltdocsMdxConfig;
   plugins?: BoltdocsPlugin[];
   collections?: BoltdocsCollectionsConfig;
   robots?: BoltdocsRobotsConfig;
   security?: BoltdocsSecurityConfig;
   seo?: BoltdocsSeoConfig;
   integrations?: BoltdocsIntegrationsConfig;
+  drafts?: BoltdocsDraftsConfig;
+  featureFlags?: Record<string, boolean | string>;
   directoryMeta?: Record<string, unknown>;
   vite?: unknown;
 }
@@ -375,6 +550,8 @@ interface ComponentRoute {
   };
   /** Draft flag */
   draft?: boolean;
+  /** Feature flags required for this page to be visible */
+  featureFlags?: string[];
   /** Short excerpt for list displays */
   excerpt?: string;
   /** Cover image for blog posts */

package/dist/{sidebar-7gIifpBX.d.cts → sidebar-DknLUI1R.d.ts}

@@ -1,10 +1,92 @@
 
 import * as React$2 from "react";
 import { ComponentType, ReactNode } from "react";
-import { Plugin } from "vite";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+import { Plugin } from "vite";
 
 //#region src/shared/types.d.ts
+/**
+ * Metadata representing a single documentation route.
+ * This information is used to build the client-side router and the sidebar navigation.
+ */
+interface RouteMeta {
+  /** The final URL path for the route (e.g., '/docs/guide/start') */
+  path: string;
+  /** The absolute filesystem path to the source markdown/mdx file */
+  componentPath: string;
+  /** The title of the page, usually extracted from frontmatter or the filename */
+  title: string;
+  /** The relative path from the docs directory, used for edit links */
+  filePath: string;
+  /** Optional description of the page (for SEO/meta tags) */
+  description?: string;
+  /** Optional explicit position for ordering in the sidebar */
+  sidebarPosition?: number;
+  /** The group (directory) this route belongs to */
+  group?: string;
+  /** The display title for the route's group */
+  groupTitle?: string;
+  /** Optional explicit position for ordering the group itself */
+  groupPosition?: number;
+  /** Optional icon for the route's group */
+  groupIcon?: string;
+  /** The sub-route group this route belongs to (from folders starting with _) */
+  subRouteGroup?: string;
+  /** Extracted markdown headings for search indexing */
+  headings?: {
+    level: number;
+    text: string;
+    id: string;
+  }[];
+  /** The locale this route belongs to, if i18n is configured */
+  locale?: string;
+  /** The version this route belongs to, if versioning is configured */
+  version?: string;
+  /** Optional badge to display next to the sidebar item (e.g., 'New', 'Experimental') */
+  badge?: BadgeValue;
+  /** Optional icon to display (Lucide icon name or raw SVG) */
+  icon?: string;
+  /** The tab this route belongs to, if tabs are configured */
+  tab?: string;
+  /** The collection this route belongs to (from [name] directories like [blog]) */
+  collection?: string;
+  /** Tags for blog posts or other taxonomy */
+  tags?: string[];
+  /** Author identifier for blog posts */
+  author?: string;
+  /** Draft flag — excluded from production builds */
+  draft?: boolean;
+  /** Feature flags required for this page to be visible */
+  featureFlags?: string[];
+  /** Short excerpt/summary for list displays */
+  excerpt?: string;
+  /** Cover image for blog posts */
+  coverImage?: string;
+  /** The extracted plain-text content of the page for search indexing */
+  _content?: string;
+  /** The raw markdown content of the page */
+  _rawContent?: string;
+  /** Extracted SEO and Open Graph metadata from frontmatter */
+  seo?: Record<string, any>;
+  /** The publication date */
+  date?: string | Date;
+  /** The last updated timestamp or date */
+  lastUpdated?: string | number | Date;
+  /** Optional category for the page */
+  category?: string;
+  /** Optional explicit order (alternative to sidebarPosition) */
+  order?: number;
+  /** Optional explicit label for the sidebar */
+  sidebarLabel?: string;
+  /** Whether the page is hidden from the sidebar */
+  sidebarHidden?: boolean;
+  /** Raw extensible frontmatter data for custom components and formatters */
+  frontmatter?: Record<string, any>;
+  /** Optional recursive child routes for deep sidebar hierarchies */
+  subRoutes?: RouteMeta[];
+  /** Clean URL segments stripped of locale/version prefixes */
+  slugParts?: string[];
+}
 /**
  * Represents a single social link in the configuration.
  */
@@ -12,12 +94,6 @@ interface BoltdocsSocialLink {
   icon: 'discord' | 'x' | 'github' | 'bluesky' | string;
   link: string;
 }
-/**
- * Configuration for the site footer.
- */
-interface BoltdocsFooterConfig {
-  text?: string;
-}
 /**
  * Theme-specific configuration options.
  */
@@ -48,7 +124,6 @@ interface BoltdocsThemeConfig {
     icon?: string;
   }>;
   socialLinks?: BoltdocsSocialLink[];
-  footer?: BoltdocsFooterConfig;
   editLink?: string;
   communityHelp?: string;
   version?: string;
@@ -118,6 +193,85 @@ type BadgeValue = string | {
   text: string;
   expires?: string;
 };
+/**
+ * Context provided to plugin lifecycle hooks.
+ */
+interface PluginContext {
+  readonly config: BoltdocsConfig$1;
+  readonly logger: PluginLogger;
+  readonly store: PluginStore;
+  readonly meta: PluginMeta;
+  readonly docsDir: string;
+  readonly rootDir: string;
+  readonly outDir: string;
+  readonly routes: RouteMeta[];
+}
+/**
+ * Logger interface for plugin logging.
+ */
+interface PluginLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string | Error): void;
+  debug(message: string): void;
+}
+/**
+ * Key-value store interface for plugins.
+ */
+interface PluginStore {
+  get<T = unknown>(pluginName: string, key: string): T | undefined;
+  set(pluginName: string, key: string, value: unknown): void;
+  has(pluginName: string, key: string): boolean;
+}
+/**
+ * Plugin metadata provided in the context.
+ */
+interface PluginMeta {
+  name: string;
+  version?: string;
+  boltdocsVersion?: string;
+}
+/**
+ * Plugin lifecycle hooks with full type safety.
+ */
+interface PluginLifecycleHooks {
+  beforeBuild?: (ctx: PluginContext) => Promise<void> | void;
+  afterBuild?: (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: {
+    code: string;
+    filePath: string;
+  }) => Promise<{
+    code: string;
+  }> | {
+    code: string;
+  };
+  transformMdx?: (ctx: PluginContext, params: {
+    code: string;
+    filePath: string;
+  }) => Promise<{
+    code: string;
+  }> | {
+    code: string;
+  };
+  transformHtml?: (ctx: PluginContext, params: {
+    html: string;
+    path: string;
+  }) => Promise<{
+    html: string;
+  }> | {
+    html: string;
+  };
+}
+/**
+ * MDX processor configuration.
+ * When `processor` is set to 'satteri', the Sätteri Rust-based compiler is used.
+ */
+interface BoltdocsMdxConfig {
+  processor?: 'unified' | 'satteri';
+}
 /**
  * Defines a Boltdocs plugin.
  *
@@ -133,8 +287,8 @@ interface BoltdocsPlugin {
   rehypePlugins?: unknown[];
   vitePlugins?: Plugin[];
   components?: Record<string, string>;
-  /** Lifecycle hooks — use the `PluginLifecycleHooks` type from the node API. */
-  hooks?: Record<string, (ctx: unknown) => Promise<void> | void>;
+  /** Lifecycle hooks with full type safety */
+  hooks?: PluginLifecycleHooks;
 }
 /**
  * Configuration for the collections (blog) feature.
@@ -236,11 +390,20 @@ interface BoltdocsVercelConfig {
   analytics?: boolean;
   speedInsights?: boolean;
 }
+interface BoltdocsPostHogConfig {
+  apiKey: string;
+  host?: string;
+  capturePageview?: boolean;
+  capturePageleave?: boolean;
+  sessionRecording?: boolean;
+  autocapture?: boolean;
+}
 interface BoltdocsIntegrationsConfig {
   analytics?: {
     ga4?: BoltdocsGA4Config;
     vercel?: BoltdocsVercelConfig;
     gtm?: BoltdocsGTMConfig;
+    posthog?: BoltdocsPostHogConfig;
   };
   search?: {
     algolia?: BoltdocsAlgoliaConfig;
@@ -250,6 +413,15 @@ interface BoltdocsIntegrationsConfig {
     custom?: BoltdocsCustomFeedbackConfig;
   };
 }
+/**
+ * Configuration for drafts visibility control.
+ */
+interface BoltdocsDraftsConfig {
+  /** If true, drafts are visible in all environments. Default: false */
+  visible?: boolean;
+  /** Environments where drafts are visible (e.g. ['development', 'staging']). Default: [] */
+  environments?: string[];
+}
 /**
  * The root configuration object for Boltdocs.
  */
@@ -260,12 +432,15 @@ interface BoltdocsConfig$1 {
   theme?: BoltdocsThemeConfig;
   i18n?: BoltdocsI18nConfig;
   versions?: BoltdocsVersionsConfig;
+  mdx?: BoltdocsMdxConfig;
   plugins?: BoltdocsPlugin[];
   collections?: BoltdocsCollectionsConfig;
   robots?: BoltdocsRobotsConfig;
   security?: BoltdocsSecurityConfig;
   seo?: BoltdocsSeoConfig;
   integrations?: BoltdocsIntegrationsConfig;
+  drafts?: BoltdocsDraftsConfig;
+  featureFlags?: Record<string, boolean | string>;
   directoryMeta?: Record<string, unknown>;
   vite?: unknown;
 }
@@ -375,6 +550,8 @@ interface ComponentRoute {
   };
   /** Draft flag */
   draft?: boolean;
+  /** Feature flags required for this page to be visible */
+  featureFlags?: string[];
   /** Short excerpt for list displays */
   excerpt?: string;
   /** Cover image for blog posts */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boltdocs",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "A lightweight documentation generator for React projects.",
   "main": "dist/node/index.mjs",
   "module": "dist/node/index.mjs",
@@ -22,6 +22,16 @@
       "import": "./dist/node/index.mjs",
       "require": "./dist/node/index.cjs"
     },
+    "./node/cache": {
+      "types": "./dist/node/cache.d.ts",
+      "import": "./dist/node/cache.mjs",
+      "require": "./dist/node/cache.cjs"
+    },
+    "./node/mdx/shiki-adapter": {
+      "types": "./dist/node/mdx/shiki-adapter.d.ts",
+      "import": "./dist/node/mdx/shiki-adapter.mjs",
+      "require": "./dist/node/mdx/shiki-adapter.cjs"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "import": "./dist/server/index.mjs",
@@ -92,9 +102,9 @@
     "unist-util-visit": "5.1.0",
     "vite": "7.0.0 || 8.0.0",
     "zod": "4.3.6",
-    "@bdocs/parser": "1.0.0",
-    "@bdocs/ssg": "0.1.1",
-    "@bdocs/plugin-image-optimizer": "0.2.1"
+    "@bdocs/parser": "1.1.0",
+    "@bdocs/plugin-image-optimizer": "0.2.1",
+    "@bdocs/ssg": "0.2.0"
   },
   "peerDependencies": {
     "react": "19.0.0",
@@ -114,7 +124,8 @@
     "jsdom": "^24.1.0",
     "tsdown": "0.21.7",
     "typescript": "5.9.3",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "@bdocs/processor-satteri": "0.1.0"
   },
   "scripts": {
     "build": "tsdown --config-loader unrun",