boltdocs 3.0.1 → 3.1.0

package/dist/shiki-adapter-fS94vy-z.d.mts

@@ -0,0 +1,534 @@
+
+import { Plugin } from "vite";
+import * as _$shiki from "shiki";
+import { CodeToHastOptions } from "shiki";
+
+//#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.
+ */
+interface BoltdocsSocialLink {
+  icon: 'discord' | 'x' | 'github' | 'bluesky' | string;
+  link: string;
+}
+/**
+ * Theme-specific configuration options.
+ */
+interface BoltdocsThemeConfig {
+  title?: string | Record<string, string>;
+  description?: string | Record<string, string>;
+  logo?: string | {
+    dark: string;
+    light: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+  };
+  navbar?: Array<{
+    label: string | Record<string, string>;
+    href: BoltdocsRoutePathWithFallback;
+    items?: Array<{
+      label: string | Record<string, string>;
+      href: BoltdocsRoutePathWithFallback;
+    }>;
+  }>;
+  sidebar?: Record<string, Array<{
+    text: string;
+    link: BoltdocsRoutePathWithFallback;
+  }>>;
+  sidebarGroups?: Record<string, {
+    title?: string | Record<string, string>;
+    icon?: string;
+  }>;
+  socialLinks?: BoltdocsSocialLink[];
+  editLink?: string;
+  communityHelp?: string;
+  version?: string;
+  githubRepo?: string;
+  favicon?: string;
+  tabs?: Array<{
+    id: string;
+    text: string | Record<string, string>;
+    icon?: string;
+  }>;
+  codeTheme?: ShikiTheme | {
+    light: ShikiTheme;
+    dark: ShikiTheme;
+  };
+}
+/**
+ * List of supported syntax highlighting themes.
+ */
+type ShikiTheme = 'github-dark' | 'github-light' | 'tokyo-night' | 'dracula' | 'nord' | 'one-dark-pro' | 'one-light';
+/**
+ * Configuration for the robots.txt file.
+ */
+type BoltdocsRobotsConfig = string | {
+  rules?: Array<{
+    userAgent: string;
+    allow?: string | string[];
+    disallow?: string | string[];
+  }>;
+  sitemaps?: string[];
+};
+/**
+ * Configuration for a specific locale.
+ */
+interface BoltdocsLocaleConfig {
+  label?: string;
+  direction?: 'ltr' | 'rtl';
+  htmlLang?: string;
+  calendar?: string;
+}
+/**
+ * Configuration for internationalization (i18n).
+ */
+interface BoltdocsI18nConfig {
+  defaultLocale: string;
+  locales: string[] | Record<string, string>;
+  localeConfigs?: Record<string, BoltdocsLocaleConfig>;
+}
+/**
+ * Configuration for a specific documentation version.
+ */
+interface BoltdocsVersionConfig {
+  label: string;
+  path: string;
+}
+/**
+ * Configuration for documentation versioning.
+ */
+interface BoltdocsVersionsConfig {
+  defaultVersion: string;
+  prefix?: string;
+  versions: BoltdocsVersionConfig[];
+}
+/**
+ * Shared badge value type used in frontmatter, RouteMeta, and ComponentRoute.
+ */
+type BadgeValue = string | {
+  text: string;
+  expires?: string;
+};
+/**
+ * Context provided to plugin lifecycle hooks.
+ */
+interface PluginContext {
+  readonly config: BoltdocsConfig;
+  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.
+ *
+ * Use the `createPlugin()` helper from the node API for full type safety and
+ * access to lifecycle hooks.
+ */
+interface BoltdocsPlugin {
+  name: string;
+  enforce?: 'pre' | 'post';
+  version?: string;
+  boltdocsVersion?: string;
+  remarkPlugins?: unknown[];
+  rehypePlugins?: unknown[];
+  vitePlugins?: Plugin[];
+  components?: Record<string, string>;
+  /** Lifecycle hooks with full type safety */
+  hooks?: PluginLifecycleHooks;
+}
+/**
+ * Configuration for the collections (blog) feature.
+ */
+interface BoltdocsCollectionsConfig {
+  /** Number of posts per page in collection listing pages. Defaults to 10. */
+  postsPerPage?: number;
+  /** The name of the default collection used by BlogList when none is specified. */
+  defaultCollection?: string;
+  /** Date format string for rendering post dates (e.g., 'MMMM dd, yyyy'). */
+  dateFormat?: string;
+  /** Field to sort posts by. Defaults to 'date'. */
+  sortBy?: 'date' | 'title' | 'sidebarPosition';
+}
+interface BoltdocsSecurityConfig {
+  headers?: Record<string, string>;
+  enableCSP?: boolean;
+  customHeaders?: Record<string, string>;
+}
+interface BoltdocsVerificationConfig {
+  google?: string;
+  bing?: string;
+  yandex?: string;
+  pinterest?: string;
+  facebook?: string;
+}
+/**
+ * Configuration for SEO.
+ */
+interface BoltdocsSeoConfig {
+  metatags?: Record<string, string>;
+  indexing?: 'all' | 'public';
+  thumbnails?: {
+    background?: string;
+  };
+  verification?: BoltdocsVerificationConfig;
+}
+/**
+ * Configuration for Google Analytics 4 (GA4).
+ */
+interface BoltdocsGA4Config {
+  measurementId: string;
+  debug?: boolean;
+  anonymizeIp?: boolean;
+  sendPageView?: boolean;
+  cookieFlags?: string;
+  autoTrack?: {
+    pageViews?: boolean;
+    downloads?: boolean;
+    externalLinks?: boolean;
+    search?: boolean;
+  };
+}
+/**
+ * Configuration for Google Tag Manager (GTM).
+ */
+interface BoltdocsGTMConfig {
+  tagId: string;
+  dataLayerName?: string;
+  preview?: string;
+}
+/**
+ * Configuration for Algolia DocSearch.
+ */
+interface BoltdocsAlgoliaConfig {
+  appId: string;
+  apiKey: string;
+  indexName: string;
+}
+/**
+ * Configuration for Giscus comments.
+ */
+interface BoltdocsGiscusConfig {
+  repo: string;
+  repoId: string;
+  category?: string;
+  categoryId?: string;
+  mapping?: 'pathname' | 'url' | 'title' | 'og:title' | 'specific' | 'number';
+  strict?: '0' | '1' | boolean;
+  reactionsEnabled?: '0' | '1' | boolean;
+  emitMetadata?: '0' | '1' | boolean;
+  inputPosition?: 'top' | 'bottom';
+  theme?: string;
+  darkTheme?: string;
+  lang?: string;
+  loading?: 'lazy' | 'eager';
+}
+/**
+ * Configuration for custom feedback system using GitHub Discussions API.
+ */
+interface BoltdocsCustomFeedbackConfig {
+  enabled: boolean;
+  owner: string;
+  repo: string;
+  categorySlug?: string;
+  endpoint?: string;
+}
+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;
+  };
+  feedback?: {
+    giscus?: BoltdocsGiscusConfig;
+    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.
+ */
+interface BoltdocsConfig {
+  siteUrl?: string;
+  docsDir?: string;
+  base?: string;
+  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;
+}
+/**
+ * Global namespace for Boltdocs types that can be augmented by generated code.
+ * This allows for strictly typed locales and versions based on the project configuration.
+ */
+declare global {
+  namespace Boltdocs {
+    interface Types {}
+    /**
+     * Marker interface augmented by generated code to provide strict route path typing.
+     * When no types have been generated (e.g., before first dev server start),
+     * keyof is never, and BoltdocsRoutePath falls back to string.
+     */
+    interface RoutePaths {}
+  }
+}
+type BoltdocsRoutePath = keyof Boltdocs.RoutePaths;
+type BoltdocsRoutePathWithFallback = BoltdocsRoutePath extends never ? string : BoltdocsRoutePath;
+//#endregion
+//#region src/shared/config-utils.d.ts
+/**
+ * Type-safe helper for defining Boltdocs configuration.
+ * This is an identity function that provides IntelliSense in both
+ * Node.js (config files) and client-side code (MDX examples).
+ *
+ * @remarks
+ * Intended for use in `boltdocs.config.ts` (Node.js context). This function
+ * is **not** available as a client-side import from `boltdocs/client`.
+ *
+ * @param config - The Boltdocs configuration object
+ */
+declare function defineConfig(config: BoltdocsConfig): BoltdocsConfig;
+//#endregion
+//#region src/node/config.d.ts
+/**
+ * Loads user's configuration file (e.g., `boltdocs.config.js` or `boltdocs.config.ts`) if it exists,
+ * merges it with the default configuration, and returns the final `BoltdocsConfig`.
+ *
+ * @param docsDir - The directory containing the documentation files
+ * @param root - The project root directory (defaults to process.cwd())
+ * @returns The merged configuration object
+ */
+declare function resolveConfig(docsDir: string, root?: string): Promise<BoltdocsConfig>;
+//#endregion
+//#region src/node/mdx/shiki-adapter.d.ts
+interface ParsedMeta {
+  title?: string;
+  lineNumbers?: boolean;
+  wordWrap?: boolean;
+  [key: string]: any;
+}
+/**
+ * Parses a meta string into a structured ParsedMeta object.
+ */
+declare function parseMetaString(metaStr: string): ParsedMeta;
+/**
+ * Unified Shiki Adapter for Boltdocs.
+ * Centralizes theme resolution, transformer configuration, and rendering logic.
+ */
+declare class ShikiAdapter {
+  private config;
+  constructor(config?: BoltdocsConfig);
+  /**
+   * Resolves the code theme from Boltdocs configuration.
+   */
+  getTheme(): ShikiTheme | {
+    light: ShikiTheme;
+    dark: ShikiTheme;
+  };
+  /**
+   * Creates a Shiki highlighter instance with the configured themes.
+   */
+  getHighlighter(): Promise<_$shiki.HighlighterCore>;
+  /**
+   * Assembles Shiki options including transformers for a specific code block.
+   */
+  getOptions(lang: string, meta: string | ParsedMeta): CodeToHastOptions;
+  /**
+   * Renders code to HTML using the Boltdocs Shiki pipeline.
+   * Safely handles highlighter exceptions by falling back to escaped pre.
+   */
+  render(code: string, lang: string, meta: string | ParsedMeta): Promise<string>;
+}
+/**
+ * Returns a cached ShikiAdapter instance.
+ * Recreates only if the relevant codeTheme configuration values change deeply.
+ */
+declare function getShikiAdapter(config?: BoltdocsConfig): ShikiAdapter;
+//#endregion
+export { resolveConfig as a, BoltdocsPlugin as c, PluginLifecycleHooks as d, PluginLogger as f, RouteMeta as h, parseMetaString as i, BoltdocsThemeConfig as l, PluginStore as m, ShikiAdapter as n, defineConfig as o, PluginMeta as p, getShikiAdapter as r, BoltdocsConfig as s, ParsedMeta as t, PluginContext as u };