@rspress/shared 1.37.2 → 1.37.3

package/dist/index-37dfa72c.d.ts

@@ -0,0 +1,772 @@
+import { RsbuildConfig, RsbuildPlugin } from '@rsbuild/core';
+import { PluggableList } from 'unified';
+
+interface ZoomOptions {
+  /**
+   * The space outside the zoomed image.
+   *
+   * @default 0
+   */
+  margin?: number
+
+  /**
+   * The background of the overlay.
+   *
+   * @default '#fff'
+   */
+  background?: string
+
+  /**
+   * The number of pixels to scroll to close the zoom.
+   *
+   * @default 40
+   */
+  scrollOffset?: number
+
+  /**
+   * The viewport to render the zoom in.
+   *
+   * @default null
+   */
+  container?: string | HTMLElement | ZoomContainer
+
+  /**
+   * The template element to display on zoom.
+   *
+   * @default null
+   */
+  template?: string | HTMLTemplateElement
+}
+
+interface ZoomContainer {
+  width?: number
+  height?: number
+  top?: number
+  bottom?: number
+  right?: number
+  left?: number
+}
+
+/**
+ * There are two ways to define what addtion routes represent.
+ * 1. Define filepath, then the content will be read from the file.
+ * 2. Define content, then then content will be written to temp file and read from it.
+ */
+interface AdditionalPage {
+    routePath: string;
+    content?: string;
+    filepath?: string;
+}
+interface RspressPlugin {
+    /**
+     * Name of the plugin.
+     */
+    name: string;
+    /**
+     * Global style
+     */
+    globalStyles?: string;
+    /**
+     * Markdown options.
+     */
+    markdown?: {
+        remarkPlugins?: PluggableList;
+        rehypePlugins?: PluggableList;
+        globalComponents?: string[];
+    };
+    /**
+     * Rsbuild config.
+     */
+    builderConfig?: RsbuildConfig;
+    /**
+     * Inject global components.
+     */
+    globalUIComponents?: (string | [string, object])[];
+    /**
+     * Modify doc config.
+     */
+    config?: (config: UserConfig, utils: {
+        addPlugin: (plugin: RspressPlugin) => void;
+        removePlugin: (pluginName: string) => void;
+    }, isProd: boolean) => UserConfig | Promise<UserConfig>;
+    /**
+     * Callback before build
+     */
+    beforeBuild?: (config: UserConfig, isProd: boolean) => void | Promise<void>;
+    /**
+     * Callback after build
+     */
+    afterBuild?: (config: UserConfig, isProd: boolean) => void | Promise<void>;
+    /**
+     * Extend every page's data
+     */
+    extendPageData?: (pageData: PageIndexInfo & {
+        [key: string]: unknown;
+    }, isProd: boolean) => void | Promise<void>;
+    /**
+     * Add custom route
+     */
+    addPages?: (config: UserConfig, isProd: boolean) => AdditionalPage[] | Promise<AdditionalPage[]>;
+    /**
+     * Add runtime modules
+     */
+    addRuntimeModules?: (config: UserConfig, isProd: boolean) => Record<string, string> | Promise<Record<string, string>>;
+    /**
+     * Callback after route generated
+     */
+    routeGenerated?: (routes: RouteMeta[], isProd: boolean) => Promise<void> | void;
+    /**
+     * Add addition ssg routes, for dynamic routes.
+     */
+    addSSGRoutes?: (config: UserConfig, isProd: boolean) => {
+        path: string;
+    }[] | Promise<{
+        path: string;
+    }[]>;
+    /**
+     * @private
+     * Modify search index data.
+     */
+    modifySearchIndexData?: (data: PageIndexInfo[], isProd: boolean) => void | Promise<void>;
+}
+
+interface Config$1 {
+    /**
+     * Whether to enable dark mode.
+     * @default true
+     */
+    darkMode?: boolean;
+    /**
+     * Custom outline title in the aside component.
+     *
+     * @default 'ON THIS PAGE'
+     */
+    outlineTitle?: string;
+    /**
+     * Whether to show the sidebar in right position.
+     */
+    outline?: boolean;
+    /**
+     * The nav items. When it's an object, the key is the version of current doc.
+     */
+    nav?: NavItem[] | {
+        [key: string]: NavItem[];
+    };
+    /**
+     * The sidebar items.
+     */
+    sidebar?: Sidebar;
+    /**
+     * Info for the edit link. If it's undefined, the edit link feature will
+     * be disabled.
+     */
+    editLink?: EditLink;
+    /**
+     * Set custom last updated text.
+     *
+     * @default 'Last updated'
+     */
+    lastUpdatedText?: string;
+    /**
+     * Set custom last updated text.
+     *
+     * @default false
+     */
+    lastUpdated?: boolean;
+    /**
+     * Set custom prev/next labels.
+     */
+    docFooter?: DocFooter;
+    /**
+     * The social links to be displayed at the end of the nav bar. Perfect for
+     * placing links to social services such as GitHub, X, Facebook, etc.
+     */
+    socialLinks?: SocialLink[];
+    /**
+     * The footer configuration.
+     */
+    footer?: Footer;
+    /**
+     * The prev page text.
+     */
+    prevPageText?: string;
+    /**
+     * The next page text.
+     */
+    nextPageText?: string;
+    /**
+     * The source code text.
+     */
+    sourceCodeText?: string;
+    /**
+     * Locale config
+     */
+    locales?: LocaleConfig[];
+    /**
+     * Whether to open the full text search
+     */
+    search?: boolean;
+    /**
+     * The placeholder of search input
+     */
+    searchPlaceholderText?: string;
+    /**
+     * The text of no search result
+     */
+    searchNoResultsText?: string;
+    /**
+     * The text of suggested query text when no search result
+     */
+    searchSuggestedQueryText?: string;
+    /**
+     * The text of overview filter
+     */
+    overview?: FilterConfig;
+    /**
+     * The behavior of hiding navbar
+     */
+    hideNavbar?: 'always' | 'auto' | 'never';
+    /**
+     * Whether to enable view transition animation for pages switching
+     */
+    enableContentAnimation?: boolean;
+    /**
+     * Whether to enable view transition animation for the theme
+     */
+    enableAppearanceAnimation?: boolean;
+    /**
+     * Enable scroll to top button on documentation
+     * @default false
+     */
+    enableScrollToTop?: boolean;
+    /**
+     * Whether to redirect to the closest locale when the user visits the site
+     * @default 'auto'
+     */
+    localeRedirect?: 'auto' | 'never';
+}
+/**
+ * locale config
+ */
+interface LocaleConfig {
+    /**
+     * Site i18n config, which will recover the locales config in the site level.
+     */
+    lang: string;
+    title?: string;
+    description?: string;
+    label: string;
+    /**
+     * Theme i18n config
+     */
+    nav?: Nav;
+    sidebar?: Sidebar;
+    outlineTitle?: string;
+    lastUpdatedText?: string;
+    lastUpdated?: boolean;
+    editLink?: EditLink;
+    prevPageText?: string;
+    nextPageText?: string;
+    sourceCodeText?: string;
+    langRoutePrefix?: string;
+    searchPlaceholderText?: string;
+    searchNoResultsText?: string;
+    searchSuggestedQueryText?: string;
+    overview?: FilterConfig;
+}
+/**
+ * The config of filter component
+ */
+interface FilterConfig {
+    filterNameText?: string;
+    filterPlaceholderText?: string;
+    filterNoResultText?: string;
+}
+type Nav = NavItem[] | {
+    [key: string]: NavItem[];
+};
+type NavItem = NavItemWithLink | NavItemWithChildren | NavItemWithLinkAndChildren;
+type NavItemWithLink = {
+    text: string;
+    link: string;
+    tag?: string;
+    activeMatch?: string;
+    position?: 'left' | 'right';
+};
+interface NavItemWithChildren {
+    text?: string;
+    tag?: string;
+    items: NavItemWithLink[];
+    position?: 'left' | 'right';
+}
+interface NavItemWithLinkAndChildren {
+    text: string;
+    link: string;
+    items: NavItemWithLink[];
+    tag?: string;
+    activeMatch?: string;
+    position?: 'left' | 'right';
+}
+type Image = string | {
+    src: string;
+    alt?: string;
+};
+interface Sidebar {
+    [path: string]: (SidebarGroup | SidebarItem | SidebarDivider | SidebarSectionHeader)[];
+}
+interface SidebarGroup {
+    text: string;
+    link?: string;
+    tag?: string;
+    items: (SidebarItem | SidebarDivider | SidebarGroup | string)[];
+    collapsible?: boolean;
+    collapsed?: boolean;
+    /**
+     * For hmr usage in development
+     */
+    _fileKey?: string;
+    overviewHeaders?: number[];
+    context?: string;
+}
+type SidebarItem = {
+    text: string;
+    link: string;
+    tag?: string;
+    /**
+     * For hmr usage in development
+     */
+    _fileKey?: string;
+    overviewHeaders?: number[];
+    context?: string;
+};
+type SidebarDivider = {
+    dividerType: 'dashed' | 'solid';
+};
+type SidebarSectionHeader = {
+    sectionHeaderText: string;
+    tag?: string;
+};
+interface EditLink {
+    /**
+     * Custom repository url for edit link.
+     */
+    docRepoBaseUrl: string;
+    /**
+     * Custom text for edit link.
+     *
+     * @default 'Edit this page'
+     */
+    text?: string;
+}
+interface DocFooter {
+    /**
+     * Custom label for previous page button.
+     */
+    prev?: SidebarItem;
+    /**
+     * Custom label for next page button.
+     */
+    next?: SidebarItem;
+}
+interface SocialLink {
+    icon: SocialLinkIcon;
+    mode: 'link' | 'text' | 'img' | 'dom';
+    content: string;
+}
+type SocialLinkIcon = 'lark' | 'discord' | 'facebook' | 'github' | 'instagram' | 'linkedin' | 'slack' | 'x' | 'youtube' | 'wechat' | 'qq' | 'juejin' | 'zhihu' | 'bilibili' | 'weibo' | 'gitlab' | 'X' | {
+    svg: string;
+};
+interface Footer {
+    message?: string;
+}
+interface LocaleLinks {
+    text: string;
+    items: LocaleLink[];
+}
+interface LocaleLink {
+    text: string;
+    link: string;
+}
+interface NormalizedSidebarGroup extends Omit<SidebarGroup, 'items'> {
+    items: (SidebarDivider | SidebarItem | NormalizedSidebarGroup)[];
+    collapsible: boolean;
+    collapsed: boolean;
+}
+interface NormalizedSidebar {
+    [path: string]: (NormalizedSidebarGroup | SidebarItem | SidebarDivider)[];
+}
+interface NormalizedLocales extends Omit<LocaleConfig, 'sidebar'> {
+    sidebar: NormalizedSidebar;
+}
+interface NormalizedConfig extends Omit<Config$1, 'locales' | 'sidebar'> {
+    locales: NormalizedLocales[];
+    sidebar: NormalizedSidebar;
+}
+
+interface Route {
+    path: string;
+    element: React.ReactElement;
+    filePath: string;
+    preload: () => Promise<PageModule<React.ComponentType<unknown>>>;
+    lang: string;
+}
+interface RouteMeta {
+    routePath: string;
+    absolutePath: string;
+    relativePath: string;
+    pageName: string;
+    lang: string;
+    version: string;
+}
+interface ReplaceRule {
+    search: string | RegExp;
+    replace: string;
+}
+interface Header {
+    id: string;
+    text: string;
+    depth: number;
+    charIndex: number;
+}
+interface Locale {
+    lang: string;
+    label: string;
+    title?: string;
+    description?: string;
+}
+type SSGConfig = boolean | {
+    strict?: boolean;
+};
+interface UserConfig<ThemeConfig = Config$1> {
+    /**
+     * The root directory of the site.
+     */
+    root?: string;
+    /**
+     * Path to the logo file in nav bar.
+     */
+    logo?: string | {
+        dark: string;
+        light: string;
+    };
+    /**
+     * The text of the logo in nav bar.
+     */
+    logoText?: string;
+    /**
+     * Base path of the site.
+     */
+    base?: string;
+    /**
+     * Path to html icon file.
+     */
+    icon?: string;
+    /**
+     * Language of the site.
+     */
+    lang?: string;
+    /**
+     * Title of the site.
+     */
+    title?: string;
+    /**
+     * Description of the site.
+     */
+    description?: string;
+    /**
+     * Head tags.
+     */
+    head?: (string | [string, Record<string, string>] | ((route: RouteMeta) => string | [string, Record<string, string>] | undefined))[];
+    /**
+     * I18n config of the site.
+     */
+    locales?: Locale[];
+    /**
+     * The i18n text data source path. Default is `i18n.json` in cwd.
+     */
+    i18nSourcePath?: string;
+    /**
+     * Theme config.
+     */
+    themeConfig?: ThemeConfig;
+    /**
+     * Rsbuild Configuration
+     */
+    builderConfig?: RsbuildConfig;
+    /**
+     * The custom config of vite-plugin-route
+     */
+    route?: RouteOptions;
+    /**
+     * The custom config of markdown compile
+     */
+    markdown?: MarkdownOptions;
+    /**
+     * Doc plugins
+     */
+    plugins?: RspressPlugin[];
+    /**
+     * Replace rule, will replace the content of the page.
+     */
+    replaceRules?: ReplaceRule[];
+    /**
+     * Output directory
+     */
+    outDir?: string;
+    /**
+     * Custom theme directory
+     */
+    themeDir?: string;
+    /**
+     * Global components
+     */
+    globalUIComponents?: (string | [string, object])[];
+    /**
+     * Global styles, is a Absolute path
+     */
+    globalStyles?: string;
+    /**
+     * Search options
+     */
+    search?: SearchOptions;
+    /**
+     * Whether to enable ssg, default is true
+     */
+    ssg?: SSGConfig;
+    /**
+     * Whether to enable medium-zoom, default is true
+     */
+    mediumZoom?: boolean | {
+        selector?: string;
+        options?: ZoomOptions;
+    };
+    /**
+     * Add some extra builder plugins
+     */
+    builderPlugins?: RsbuildPlugin[];
+    /**
+     * Multi version config
+     */
+    multiVersion?: {
+        /**
+         * The default version
+         */
+        default?: string;
+        /**
+         * The version list, such as ['v1', 'v2']
+         */
+        versions: string[];
+    };
+}
+type RemoveUnderscoreProps<T> = {
+    [K in keyof T as K extends `_${string}` ? never : K]: T[K];
+};
+type BaseRuntimePageInfo = Omit<RemoveUnderscoreProps<PageIndexInfo>, 'id' | 'content' | 'domain'>;
+interface SiteData<ThemeConfig = NormalizedConfig> {
+    root: string;
+    base: string;
+    lang: string;
+    route: RouteOptions;
+    locales: {
+        lang: string;
+        label: string;
+    }[];
+    title: string;
+    description: string;
+    icon: string;
+    themeConfig: ThemeConfig;
+    logo: string | {
+        dark: string;
+        light: string;
+    };
+    logoText: string;
+    pages: BaseRuntimePageInfo[];
+    search: SearchOptions;
+    ssg: boolean;
+    markdown: {
+        showLineNumbers: boolean;
+        defaultWrapCode: boolean;
+        codeHighlighter: 'prism' | 'shiki';
+    };
+    multiVersion: {
+        default: string;
+        versions: string[];
+    };
+}
+/**
+ * @description search-index.json file
+ * "_foo" is the private field that won't be written to search-index.json file
+ * and should not be used in the runtime (usePageData).
+ */
+type PageIndexInfo = {
+    id: number;
+    title: string;
+    routePath: string;
+    toc: Header[];
+    content: string;
+    _html: string;
+    frontmatter: Record<string, unknown>;
+    lang: string;
+    version: string;
+    domain: string;
+    _filepath: string;
+    _relativePath: string;
+};
+type RemotePageInfo = PageIndexInfo & {
+    _matchesPosition: {
+        content: {
+            start: number;
+            length: number;
+        }[];
+    };
+};
+interface Hero {
+    name: string;
+    text: string;
+    tagline: string;
+    image?: {
+        src: string | {
+            dark: string;
+            light: string;
+        };
+        alt: string;
+        /**
+         * `srcset` and `sizes` are attributes of `<img>` tag. Please refer to https://mdn.io/srcset for the usage.
+         * When the value is an array, rspress will join array members with commas.
+         **/
+        sizes?: string | string[];
+        srcset?: string | string[];
+    };
+    actions: {
+        text: string;
+        link: string;
+        theme: 'brand' | 'alt';
+    }[];
+}
+interface Feature {
+    icon: string;
+    title: string;
+    details: string;
+    span?: number;
+    link?: string;
+}
+interface PageModule<T extends React.ComponentType<unknown>> {
+    default: T;
+    frontmatter?: FrontMatterMeta;
+    content?: string;
+    [key: string]: unknown;
+}
+type PageType = 'home' | 'doc' | 'custom' | '404' | 'blank';
+interface FrontMatterMeta {
+    title?: string;
+    description?: string;
+    overview?: boolean;
+    pageType?: PageType;
+    features?: Feature[];
+    hero?: Hero;
+    sidebar?: boolean;
+    outline?: boolean;
+    lineNumbers?: boolean;
+    overviewHeaders?: number;
+    titleSuffix?: string;
+    head?: [string, Record<string, string>][];
+    context?: string;
+    [key: string]: unknown;
+}
+interface PageData {
+    siteData: SiteData<Config$1>;
+    page: BaseRuntimePageInfo & {
+        pagePath: string;
+        lastUpdatedTime?: string;
+        description?: string;
+        pageType: PageType;
+        [key: string]: unknown;
+    };
+}
+interface RouteOptions {
+    /**
+     * The extension name of the filepath that will be converted to a route
+     * @default ['js','jsx','ts','tsx','md','mdx']
+     */
+    extensions?: string[];
+    /**
+     * Include extra files from being converted to routes
+     */
+    include?: string[];
+    /**
+     * Exclude files from being converted to routes
+     */
+    exclude?: string[];
+    /**
+     * use links without .html files
+     */
+    cleanUrls?: boolean;
+}
+interface SearchHooks {
+    /**
+     * The search hook function path. The corresponding file should export a function named `onSearch`.
+     */
+    searchHooks?: string;
+}
+type LocalSearchOptions = SearchHooks & {
+    mode?: 'local';
+    /**
+     * Whether to generate separate search index for each version
+     */
+    versioned?: boolean;
+};
+type RemoteSearchIndexInfo = string | {
+    value: string;
+    label: string;
+};
+type RemoteSearchOptions = SearchHooks & {
+    mode: 'remote';
+    apiUrl: string;
+    domain?: string;
+    indexName: string;
+    searchIndexes?: RemoteSearchIndexInfo[];
+    searchLoading?: boolean;
+};
+type SearchOptions = LocalSearchOptions | RemoteSearchOptions | false;
+interface MdxRsOptions {
+    /**
+     * Determine whether the file use mdxRs compiler
+     */
+    include?: (filepath: string) => boolean;
+}
+interface MarkdownOptions {
+    remarkPlugins?: PluggableList;
+    rehypePlugins?: PluggableList;
+    /**
+     * Whether to enable check dead links, default is false
+     */
+    checkDeadLinks?: boolean;
+    showLineNumbers?: boolean;
+    /**
+     * Whether to wrap code by default, default is false
+     */
+    defaultWrapCode?: boolean;
+    /**
+     * Register global components in mdx files
+     */
+    globalComponents?: string[];
+    /**
+     * Code highlighter, default is prism for performance reason
+     */
+    codeHighlighter?: 'prism' | 'shiki';
+    /**
+     * Register prism languages
+     */
+    highlightLanguages?: (string | [string, string])[];
+    /**
+     * Whether to enable mdx-rs, default is true
+     */
+    mdxRs?: boolean | MdxRsOptions;
+    /**
+     * @deprecated, use `mdxRs` instead
+     */
+    experimentalMdxRs?: boolean;
+}
+type Config = UserConfig | Promise<UserConfig> | ((env: any) => UserConfig | Promise<UserConfig>);
+
+export type { AdditionalPage as A, BaseRuntimePageInfo as B, Config$1 as C, SidebarGroup as D, SidebarItem as E, Feature as F, SidebarDivider as G, Header as H, Image as I, SidebarSectionHeader as J, EditLink as K, Locale as L, MdxRsOptions as M, NormalizedConfig as N, DocFooter as O, PageIndexInfo as P, SocialLink as Q, RspressPlugin as R, SSGConfig as S, SocialLinkIcon as T, UserConfig as U, Footer as V, LocaleLinks as W, LocaleLink as X, NormalizedSidebarGroup as Y, NormalizedSidebar as Z, NormalizedLocales as _, Route as a, RouteMeta as b, ReplaceRule as c, SiteData as d, RemotePageInfo as e, Hero as f, PageModule as g, PageType as h, FrontMatterMeta as i, PageData as j, RouteOptions as k, SearchHooks as l, LocalSearchOptions as m, RemoteSearchIndexInfo as n, RemoteSearchOptions as o, SearchOptions as p, MarkdownOptions as q, Config as r, LocaleConfig as s, FilterConfig as t, Nav as u, NavItem as v, NavItemWithLink as w, NavItemWithChildren as x, NavItemWithLinkAndChildren as y, Sidebar as z };