vitepress 2.0.0-alpha.2 → 2.0.0-alpha.21

package/types/default-theme.d.ts

@@ -1,14 +1,37 @@
-import type MarkdownIt from 'markdown-it'
-import type { Options as MiniSearchOptions } from 'minisearch'
-import type { ComputedRef, Ref, ShallowRef } from 'vue'
+import type { Options as _MiniSearchOptions } from 'minisearch'
+import type { ComputedRef, ShallowRef } from 'vue'
+
 import type { DocSearchProps } from './docsearch.js'
-import type {
-  LocalSearchTranslations,
-  PageSplitSection
-} from './local-search.js'
-import type { Awaitable, MarkdownEnv, PageData } from './shared.js'
+import type { LocalSearchTranslations } from './local-search.js'
+import type { Header, PageData, Route, VitePressData } from './shared.js'
 
 export namespace DefaultTheme {
+  /**
+   * The layout state returned by `useLayout` from `vitepress/theme`.
+   */
+  export interface Layout {
+    isHome: ComputedRef<boolean>
+
+    sidebar: Readonly<ShallowRef<SidebarItem[]>>
+    sidebarGroups: ComputedRef<SidebarItem[]>
+    hasSidebar: ComputedRef<boolean>
+    isSidebarEnabled: ComputedRef<boolean>
+
+    hasAside: ComputedRef<boolean>
+    leftAside: ComputedRef<boolean>
+
+    /**
+     * The outline headers of the current page.
+     */
+    headers: Readonly<ShallowRef<OutlineItem[]>>
+    /**
+     * Whether the current page has a local nav. Local nav is shown when the
+     * "outline" is present in the page. However, note that the actual
+     * local nav visibility depends on the screen width as well.
+     */
+    hasLocalNav: ComputedRef<boolean>
+  }
+
   export interface Config {
     /**
      * The logo file of the site.
@@ -35,13 +58,6 @@ export namespace DefaultTheme {
      */
     outline?: Outline | Outline['level'] | false
 
-    /**
-     * @deprecated Use `outline.label` instead.
-     *
-     * @default 'On this page'
-     */
-    outlineTitle?: string
-
     /**
      * The nav items.
      */
@@ -67,15 +83,6 @@ export namespace DefaultTheme {
      */
     editLink?: EditLink
 
-    /**
-     * @deprecated Use `lastUpdated.text` instead.
-     *
-     * Set custom last updated text.
-     *
-     * @default 'Last updated'
-     */
-    lastUpdatedText?: string
-
     lastUpdated?: LastUpdatedOptions
 
     /**
@@ -126,6 +133,29 @@ export namespace DefaultTheme {
      */
     langMenuLabel?: string
 
+    /**
+     * Accessible label of the main navigation landmarks (navbar menu and
+     * the mobile menu).
+     *
+     * @default 'Main Navigation'
+     */
+    navMenuLabel?: string
+
+    /**
+     * Set custom `aria-label` for the mobile menu (hamburger) button.
+     *
+     * @default 'Menu'
+     */
+    mobileMenuLabel?: string
+
+    /**
+     * Set custom `aria-label` for the `⋯` overflow menu button in the
+     * navbar, which collects nav items and controls that don't fit.
+     *
+     * @default 'More options'
+     */
+    extraMenuLabel?: string
+
     /**
      * @default 'Skip to content'
      */
@@ -135,22 +165,19 @@ export namespace DefaultTheme {
       | { provider: 'local'; options?: LocalSearchOptions }
       | { provider: 'algolia'; options: AlgoliaSearchOptions }
 
-    /**
-     * @deprecated Use `search` instead.
-     */
-    algolia?: AlgoliaSearchOptions
-
     /**
      * The carbon ads options. Leave it undefined to disable the ads feature.
      */
     carbonAds?: CarbonAdsOptions
 
     /**
-     * Changing locale when current url is `/foo` will redirect to `/locale/foo`.
+     * Changing locale when current url is `/foo` redirects to `/locale/foo`.
+     * Set to `false` to disable this behavior, or provide a function to
+     * customize the target locale link.
      *
      * @default true
      */
-    i18nRouting?: boolean
+    i18nRouting?: boolean | I18nRouting
 
     /**
      * Show external link icon in Markdown links.
@@ -159,12 +186,28 @@ export namespace DefaultTheme {
      */
     externalLinkIcon?: boolean
 
+    /**
+     * Color custom containers, GitHub-flavored alerts, and badges on a
+     * graded severity scale (danger red > warning orange > caution yellow)
+     * instead of matching GitHub's alert colors, where caution is red and
+     * warning is yellow.
+     *
+     * @default false
+     */
+    gradedContainers?: boolean
+
     /**
      * Customize text of 404 page.
      */
     notFound?: NotFoundOptions
   }
 
+  export type I18nRouting = (
+    data: VitePressData<Config>,
+    route: Route,
+    targetLocale: string
+  ) => string
+
   // nav -----------------------------------------------------------------------
 
   export type NavItem = NavItemComponent | NavItemWithLink | NavItemWithChildren
@@ -176,7 +219,7 @@ export namespace DefaultTheme {
 
   export interface NavItemWithLink {
     text: string
-    link: string
+    link: string | ((payload: PageData) => string)
     items?: never
 
     /**
@@ -277,22 +320,6 @@ export namespace DefaultTheme {
     target?: string
   }
 
-  /**
-   * ReturnType of `useSidebar`
-   */
-  export interface DocSidebar {
-    isOpen: Ref<boolean>
-    sidebar: ComputedRef<SidebarItem[]>
-    sidebarGroups: ComputedRef<SidebarItem[]>
-    hasSidebar: ComputedRef<boolean>
-    hasAside: ComputedRef<boolean>
-    leftAside: ComputedRef<boolean>
-    isSidebarEnabled: ComputedRef<boolean>
-    open: () => void
-    close: () => void
-    toggle: () => void
-  }
-
   // edit link -----------------------------------------------------------------
 
   export interface EditLink {
@@ -336,6 +363,7 @@ export namespace DefaultTheme {
     icon: SocialLinkIcon
     link: string
     ariaLabel?: string
+    target?: string
   }
 
   export type SocialLinkIcon = string | { svg: string }
@@ -361,25 +389,6 @@ export namespace DefaultTheme {
     actionText?: string
   }
 
-  // local nav -----------------------------------------------------------------
-
-  /**
-   * ReturnType of `useLocalNav`.
-   */
-  export interface DocLocalNav {
-    /**
-     * The outline headers of the current page.
-     */
-    headers: ShallowRef<any>
-
-    /**
-     * Whether the current page has a local nav. Local nav is shown when the
-     * "outline" is present in the page. However, note that the actual
-     * local nav visibility depends on the screen width as well.
-     */
-    hasLocalNav: ComputedRef<boolean>
-  }
-
   // outline -------------------------------------------------------------------
 
   export interface Outline {
@@ -387,15 +396,14 @@ export namespace DefaultTheme {
     label?: string
   }
 
+  export type OutlineItem = Omit<Header, 'slug' | 'children'> & {
+    element: HTMLHeadElement
+    children?: OutlineItem[]
+  }
+
   // local search --------------------------------------------------------------
 
   export interface LocalSearchOptions {
-    /**
-     * @default false
-     * @deprecated Use `detailedView: false` instead.
-     */
-    disableDetailedView?: boolean
-
     /**
      * If `true`, the detailed view will be enabled by default.
      * If `false`, the detailed view will be disabled.
@@ -413,46 +421,21 @@ export namespace DefaultTheme {
     translations?: LocalSearchTranslations
     locales?: Record<string, Partial<Omit<LocalSearchOptions, 'locales'>>>
 
-    miniSearch?: {
-      /**
-       * @see https://lucaong.github.io/minisearch/types/MiniSearch.Options.html
-       */
-      options?: Pick<
-        MiniSearchOptions,
-        'extractField' | 'tokenize' | 'processTerm'
-      >
-      /**
-       * @see https://lucaong.github.io/minisearch/types/MiniSearch.SearchOptions.html
-       */
-      searchOptions?: MiniSearchOptions['searchOptions']
-
-      /**
-       * Overrides the default regex based page splitter.
-       * Supports async generator, making it possible to run in true parallel
-       * (when used along with `node:child_process` or `worker_threads`)
-       * ---
-       * This should be especially useful for scalability reasons.
-       * ---
-       * @param {string} path - absolute path to the markdown source file
-       * @param {string} html - document page rendered as html
-       */
-      _splitIntoSections?: (
-        path: string,
-        html: string
-      ) =>
-        | AsyncGenerator<PageSplitSection>
-        | Generator<PageSplitSection>
-        | Awaitable<PageSplitSection[]>
-    }
-    /**
-     * Allows transformation of content before indexing (node only)
-     * Return empty string to skip indexing
-     */
-    _render?: (
-      src: string,
-      env: MarkdownEnv,
-      md: MarkdownIt
-    ) => Awaitable<string>
+    miniSearch?: MiniSearchOptions
+  }
+
+  interface MiniSearchOptions {
+    /**
+     * @see https://lucaong.github.io/minisearch/types/MiniSearch.Options.html
+     */
+    options?: Pick<
+      _MiniSearchOptions,
+      'extractField' | 'tokenize' | 'processTerm'
+    >
+    /**
+     * @see https://lucaong.github.io/minisearch/types/MiniSearch.SearchOptions.html
+     */
+    searchOptions?: _MiniSearchOptions['searchOptions']
   }
 
   // algolia -------------------------------------------------------------------
@@ -462,6 +445,11 @@ export namespace DefaultTheme {
    * `@docsearch/react/dist/esm/DocSearch.d.ts`
    */
   export interface AlgoliaSearchOptions extends DocSearchProps {
+    /**
+     * Locale-specific overrides for Algolia search options.
+     * These options will be deeply merged with the root options,
+     * except for `searchParameters`, which is fully replaced.
+     */
     locales?: Record<string, Partial<DocSearchProps>>
   }
 
@@ -470,6 +458,7 @@ export namespace DefaultTheme {
   export interface CarbonAdsOptions {
     code: string
     placement: string
+    format?: 'classic' | 'responsive' | 'cover'
   }
 
   // last updated --------------------------------------------------------------
@@ -509,6 +498,13 @@ export namespace DefaultTheme {
      */
     quote?: string
 
+    /**
+     * Target of the home link.
+     *
+     * @default '/'
+     */
+    link?: string
+
     /**
      * Set aria label for home link.
      *

package/types/docsearch.d.ts

@@ -1,144 +1,63 @@
-export interface DocSearchProps {
-  appId: string
-  apiKey: string
-  indexName: string
-  placeholder?: string
-  searchParameters?: SearchOptions
-  disableUserPersonalization?: boolean
-  initialQuery?: string
+import { type DocSearchProps as DocSearchPropsJS } from '@docsearch/js'
+import { type SidepanelProps as SidepanelPropsBase } from '@docsearch/sidepanel-js'
+
+export type DocSearchProps = Partial<
+  Pick<
+    DocSearchPropsJS,
+    | 'appId'
+    | 'apiKey'
+    | 'placeholder'
+    | 'maxResultsPerGroup'
+    | 'disableUserPersonalization'
+    | 'initialQuery'
+    | 'translations'
+    | 'recentSearchesLimit'
+    | 'recentSearchesWithFavoritesLimit'
+  >
+> & {
+  /**
+   * Name of the algolia index to query.
+   */
+  indexName?: string
+  /**
+   * Additional algolia search parameters to merge into each query.
+   */
+  searchParameters?: DocSearchPropsJS['searchParameters']
+  /**
+   * Insights client integration options to send analytics events.
+   */
   insights?: boolean
-  translations?: DocSearchTranslations
-}
-
-export interface SearchOptions {
-  query?: string
-  similarQuery?: string
-  facetFilters?: string | string[]
-  optionalFilters?: string | string[]
-  numericFilters?: string | string[]
-  tagFilters?: string | string[]
-  sumOrFiltersScores?: boolean
-  filters?: string
-  page?: number
-  hitsPerPage?: number
-  offset?: number
-  length?: number
-  attributesToHighlight?: string[]
-  attributesToSnippet?: string[]
-  attributesToRetrieve?: string[]
-  highlightPreTag?: string
-  highlightPostTag?: string
-  snippetEllipsisText?: string
-  restrictHighlightAndSnippetArrays?: boolean
-  facets?: string[]
-  maxValuesPerFacet?: number
-  facetingAfterDistinct?: boolean
-  minWordSizefor1Typo?: number
-  minWordSizefor2Typos?: number
-  allowTyposOnNumericTokens?: boolean
-  disableTypoToleranceOnAttributes?: string[]
-  queryType?: 'prefixLast' | 'prefixAll' | 'prefixNone'
-  removeWordsIfNoResults?: 'none' | 'lastWords' | 'firstWords' | 'allOptional'
-  advancedSyntax?: boolean
-  advancedSyntaxFeatures?: ('exactPhrase' | 'excludeWords')[]
-  optionalWords?: string | string[]
-  disableExactOnAttributes?: string[]
-  exactOnSingleWordQuery?: 'attribute' | 'none' | 'word'
-  alternativesAsExact?: (
-    | 'ignorePlurals'
-    | 'singleWordSynonym'
-    | 'multiWordsSynonym'
-  )[]
-  enableRules?: boolean
-  ruleContexts?: string[]
-  distinct?: boolean | number
-  analytics?: boolean
-  analyticsTags?: string[]
-  synonyms?: boolean
-  replaceSynonymsInHighlight?: boolean
-  minProximity?: number
-  responseFields?: string[]
-  maxFacetHits?: number
-  percentileComputation?: boolean
-  clickAnalytics?: boolean
-  personalizationImpact?: number
-  enablePersonalization?: boolean
-  restrictSearchableAttributes?: string[]
-  sortFacetValuesBy?: 'count' | 'alpha'
-  typoTolerance?: boolean | 'min' | 'strict'
-  aroundLatLng?: string
-  aroundLatLngViaIP?: boolean
-  aroundRadius?: number | 'all'
-  aroundPrecision?: number | { from: number; value: number }[]
-  minimumAroundRadius?: number
-  insideBoundingBox?: number[][]
-  insidePolygon?: number[][]
-  ignorePlurals?: boolean | string[]
-  removeStopWords?: boolean | string[]
-  naturalLanguages?: string[]
-  getRankingInfo?: boolean
-  userToken?: string
-  enableABTest?: boolean
-  decompoundQuery?: boolean
-  relevancyStrictness?: number
-}
-
-export interface DocSearchTranslations {
-  button?: ButtonTranslations
-  modal?: ModalTranslations
-}
-
-export interface ButtonTranslations {
-  buttonText?: string
-  buttonAriaLabel?: string
-}
-
-export interface ModalTranslations extends ScreenStateTranslations {
-  searchBox?: SearchBoxTranslations
-  footer?: FooterTranslations
-}
-
-export interface ScreenStateTranslations {
-  errorScreen?: ErrorScreenTranslations
-  startScreen?: StartScreenTranslations
-  noResultsScreen?: NoResultsScreenTranslations
-}
-
-export interface SearchBoxTranslations {
-  resetButtonTitle?: string
-  resetButtonAriaLabel?: string
-  cancelButtonText?: string
-  cancelButtonAriaLabel?: string
-}
-
-export interface FooterTranslations {
-  selectText?: string
-  selectKeyAriaLabel?: string
-  navigateText?: string
-  navigateUpKeyAriaLabel?: string
-  navigateDownKeyAriaLabel?: string
-  closeText?: string
-  closeKeyAriaLabel?: string
-  searchByText?: string
-}
-
-export interface ErrorScreenTranslations {
-  titleText?: string
-  helpText?: string
-}
-
-export interface StartScreenTranslations {
-  recentSearchesTitle?: string
-  noRecentSearchesText?: string
-  saveRecentSearchButtonTitle?: string
-  removeRecentSearchButtonTitle?: string
-  favoriteSearchesTitle?: string
-  removeFavoriteSearchButtonTitle?: string
-}
-
-export interface NoResultsScreenTranslations {
-  noResultsText?: string
-  suggestedQueryText?: string
-  reportMissingResultsText?: string
-  reportMissingResultsLinkText?: string
+  /**
+   * Configuration or assistant id to enable ask ai mode. Pass a string assistant id or a full config object.
+   */
+  askAi?: DocSearchAskAi | string
+  /**
+   * Ask AI side panel integration mode.
+   *
+   * - 'auto': infer hybrid vs sidePanel-only from provided config
+   * - 'sidePanel': force sidePanel-only even if keyword search is configured
+   * - 'hybrid': force hybrid (error if keyword search is not configured)
+   * - 'modal': force modal even if sidePanel is configured (ask ai in modal stays in modal)
+   *
+   * @default 'auto'
+   */
+  mode?: 'auto' | 'sidePanel' | 'hybrid' | 'modal'
+}
+
+export type DocSearchAskAi = Partial<
+  Exclude<DocSearchPropsJS['askAi'], string | undefined>
+> & {
+  /**
+   * Ask AI side panel configuration.
+   */
+  sidePanel?: boolean | SidepanelProps
+}
+
+export type SidepanelProps = Partial<
+  Pick<SidepanelPropsBase, 'button' | 'keyboardShortcuts'>
+> & {
+  /**
+   * Props specific to the Sidepanel panel.
+   */
+  panel?: Omit<NonNullable<SidepanelPropsBase['panel']>, 'portalContainer'>
 }