docs(types): rewrite JSDoc comments in shared.d.ts

Standardizes the tone across the file and documents all previously
undocumented types and members.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

types/shared.d.ts

@@ -4,9 +4,16 @@ import type { Component, Ref } from 'vue'
 import type { SSRContext } from 'vue/server-renderer'
 export type { DefaultTheme } from './default-theme.js'
 
+/**
+ * A value of type `T`, or a promise resolving to it.
+ */
 export type Awaitable<T> = T | PromiseLike<T>
 
-type DeepPartial<T> =
+/**
+ * Recursively makes all properties of `T` optional, leaving non-plain
+ * objects (dates, regexps, functions, collections) as-is.
+ */
+export type DeepPartial<T> =
   T extends Record<string, any>
     ? T extends
         | Date
@@ -19,67 +26,105 @@ type DeepPartial<T> =
       : { [P in keyof T]?: DeepPartial<T[P]> }
     : T
 
+/**
+ * The data of a page, available on both server and client.
+ */
 export interface PageData {
+  /**
+   * The path of the page relative to the source directory, with rewrites
+   * applied. Determines the URL of the page.
+   */
   relativePath: string
   /**
-   * differs from relativePath in case of path rewrites
-   * empty string if the page is virtual (e.g. 404 page)
+   * The path of the actual source file relative to the source directory.
+   * Differs from `relativePath` when path rewrites are in use, points to
+   * the route template for dynamic routes, and is an empty string if the
+   * page is virtual (e.g. the 404 page).
    */
   filePath: string
+  /**
+   * The title of the page, from its frontmatter or its first level-1
+   * heading.
+   */
   title: string
+  /**
+   * The suffix appended to the title (`title | suffix`), or a template
+   * containing the `:title` token. Set to `false` to use the title as-is.
+   */
   titleTemplate?: string | boolean
+  /**
+   * The description of the page, from its frontmatter.
+   */
   description: string
+  /**
+   * The section headers extracted from the page.
+   */
   headers: Header[]
+  /**
+   * The frontmatter of the page.
+   */
   frontmatter: Record<string, any>
+  /**
+   * The route params of the page, if it belongs to a dynamic route.
+   */
   params?: Record<string, any>
+  /**
+   * Whether the page is the not-found (404) page.
+   */
   isNotFound?: boolean
+  /**
+   * The timestamp (in milliseconds) of the last update, from the page's
+   * frontmatter or its last git commit.
+   */
   lastUpdated?: number
 }
 
 /**
- * SFC block extracted from markdown
+ * A block of the Vue SFC generated from a markdown source file.
  */
 export interface SfcBlock {
   /**
-   * The type of the block
+   * The type of the block.
    */
   type: string
   /**
-   * The content, including open-tag and close-tag
+   * The content of the block, including its open and close tags.
    */
   content: string
   /**
-   * The content that stripped open-tag and close-tag off
+   * The content of the block, with its open and close tags stripped.
    */
   contentStripped: string
   /**
-   * The open-tag
+   * The open tag of the block.
    */
   tagOpen: string
   /**
-   * The close-tag
+   * The close tag of the block.
    */
   tagClose: string
 }
 
+/**
+ * The SFC blocks extracted from a markdown source file.
+ */
 export interface MarkdownSfcBlocks {
   /**
-   * The `<template>` block
+   * The `<template>` block.
    */
   template: SfcBlock | null
   /**
-   * The common `<script>` block
+   * The common `<script>` block.
    */
   script: SfcBlock | null
   /**
-   * The `<script setup>` block
+   * The `<script setup>` block.
    */
   scriptSetup: SfcBlock | null
   /**
-   * All `<script>` blocks.
-   *
-   * By default, SFC only allows one `<script>` block and one `<script setup>` block.
-   * However, some tools may support different types of `<script>`s, so we keep all of them here.
+   * All `<script>` blocks. An SFC normally allows a single `<script>` block
+   * and a single `<script setup>` block, but some tools may support more,
+   * so all of them are kept here.
    */
   scripts: SfcBlock[]
   /**
@@ -92,130 +137,316 @@ export interface MarkdownSfcBlocks {
   customBlocks: SfcBlock[]
 }
 
+/**
+ * A section header extracted from a page.
+ */
 export interface Header {
   /**
-   * The level of the header
-   *
-   * `1` to `6` for `<h1>` to `<h6>`
+   * The level of the header, `1` to `6` for `<h1>` to `<h6>`.
    */
   level: number
   /**
-   * The title of the header
+   * The title of the header.
    */
   title: string
   /**
-   * The slug of the header
-   *
-   * Typically the `id` attr of the header anchor
+   * The slug of the header, typically the `id` attribute of its anchor.
    */
   slug: string
   /**
-   * Link of the header
-   *
-   * Typically using `#${slug}` as the anchor hash
+   * The link of the header, typically `#${slug}`.
    */
   link: string
   /**
-   * The children of the header
+   * The nested child headers.
    */
   children: Header[]
 }
 
+/**
+ * Site-level data, resolved from the user config for the active locale.
+ */
 export interface SiteData<ThemeConfig = any> {
+  /**
+   * The base URL the site is deployed at.
+   * @default '/'
+   */
   base: string
+  /**
+   * Whether VitePress generates URLs without a trailing `.html`.
+   * @default false
+   */
   cleanUrls?: boolean
+  /**
+   * The `lang` attribute of the site.
+   * @default 'en-US'
+   */
   lang: string
+  /**
+   * The text direction (`dir` attribute) of the site.
+   * @default 'ltr'
+   */
   dir: string
+  /**
+   * The title of the site.
+   * @default 'VitePress'
+   */
   title: string
+  /**
+   * The suffix appended to page titles (`title | suffix`), or a template
+   * containing the `:title` token. Set to `false` to use page titles as-is.
+   */
   titleTemplate?: string | boolean
+  /**
+   * The description of the site.
+   * @default 'A VitePress site'
+   */
   description: string
+  /**
+   * Additional elements to render in the `<head>` tag of every page.
+   */
   head: HeadConfig[]
+  /**
+   * The dark mode behavior: `true` for a toggleable dark mode, `'dark'` to
+   * default to it, `'force-dark'`/`'force-auto'` to force the mode, or
+   * options for `useDark` from `@vueuse/core`. `false` disables it.
+   * @default true
+   */
   appearance:
     | boolean
     | 'dark'
     | 'force-dark'
     | 'force-auto'
     | (Omit<UseDarkOptions, 'initialValue'> & { initialValue?: 'dark' })
+  /**
+   * The config of the active theme.
+   */
   themeConfig: ThemeConfig
+  /**
+   * The config overrides of each locale, keyed by its directory
+   * (`'root'` for the default locale).
+   */
   locales: LocaleConfig<ThemeConfig>
+  /**
+   * The key of the active locale in `locales`.
+   */
   localeIndex?: string
+  /**
+   * Props passed to the wrapper element rendered by the `Content` component.
+   */
   contentProps?: Record<string, any>
+  /**
+   * Client router options.
+   */
   router: {
+    /**
+     * Whether links are prefetched when they enter the viewport.
+     * @default true
+     */
     prefetchLinks: boolean
   }
+  /**
+   * Config overrides applied to pages by directory: either a dict mapping a
+   * directory (e.g. `/guide/`) to overrides, where deeper directories take
+   * precedence, or a function returning the overrides to apply for a page.
+   */
   additionalConfig?:
     AdditionalConfigDict<ThemeConfig> | AdditionalConfigLoader<ThemeConfig>
 }
 
+/**
+ * Reactive data exposed by the `useData` composable.
+ */
 export interface VitePressData<T = any> {
   /**
-   * site-level metadata
+   * The site-level data for the active locale.
    */
   site: Ref<SiteData<T>>
   /**
-   * themeConfig from .vitepress/config.js
+   * The config of the active theme.
    */
   theme: Ref<T>
   /**
-   * page-level metadata
+   * The data of the current page.
    */
   page: Ref<PageData>
   /**
-   * page frontmatter data
+   * The frontmatter of the current page.
    */
   frontmatter: Ref<PageData['frontmatter']>
   /**
-   * dynamic route params
+   * The route params of the current page.
    */
   params: Ref<PageData['params']>
+  /**
+   * The resolved title of the current page.
+   */
   title: Ref<string>
+  /**
+   * The resolved description of the current page.
+   */
   description: Ref<string>
+  /**
+   * The `lang` attribute of the active locale.
+   */
   lang: Ref<string>
+  /**
+   * The text direction of the active locale.
+   */
   dir: Ref<string>
+  /**
+   * The key of the active locale.
+   */
   localeIndex: Ref<string>
+  /**
+   * Whether dark mode is currently active.
+   */
   isDark: Ref<boolean>
 }
 
+/**
+ * The currently matched route.
+ */
 export interface Route {
+  /**
+   * The pathname of the current URL.
+   */
   path: string
+  /**
+   * The hash of the current URL, including the leading `#`.
+   */
   hash: string
+  /**
+   * The query string of the current URL, including the leading `?`.
+   */
   query: string
+  /**
+   * The data of the matched page.
+   */
   data: PageData
+  /**
+   * The component of the matched page, once resolved.
+   */
   component: Component | null
 }
 
+/**
+ * A head entry as `[tag, attrs]` or `[tag, attrs, innerHTML]`, e.g.
+ * `['link', { rel: 'icon', href: '/favicon.ico' }]`.
+ */
 export type HeadConfig =
   [string, Record<string, string>] | [string, Record<string, string>, string]
 
+/**
+ * The payload sent to the client when page data is hot-updated.
+ */
 export interface PageDataPayload {
+  /**
+   * The path of the updated page relative to the source directory, with
+   * rewrites applied and a leading slash.
+   */
   path: string
+  /**
+   * The new data of the updated page.
+   */
   pageData: PageData
 }
 
+/**
+ * The SSR context used when rendering a page to static HTML.
+ */
 export interface SSGContext extends SSRContext {
+  /**
+   * The rendered HTML content of the page.
+   */
   content: string
-  /** @experimental */
+  /**
+   * The names of the social icons used on the page, collected so that only
+   * the styles of used icons are emitted.
+   * @experimental
+   */
   vpSocialIcons: Set<string>
 }
 
+/**
+ * The site config options that can be overridden per locale.
+ */
 export interface LocaleSpecificConfig<ThemeConfig = any> {
+  /**
+   * The `lang` attribute of the locale.
+   */
   lang?: string
+  /**
+   * The text direction of the locale.
+   */
   dir?: string
+  /**
+   * The title of the site in the locale.
+   */
   title?: string
+  /**
+   * The suffix appended to page titles (`title | suffix`), or a template
+   * containing the `:title` token. Set to `false` to use page titles as-is.
+   */
   titleTemplate?: string | boolean
+  /**
+   * The description of the site in the locale.
+   */
   description?: string
+  /**
+   * Additional head entries for the locale, merged with the root ones.
+   */
   head?: HeadConfig[]
+  /**
+   * Theme config overrides for the locale, merged with the root theme
+   * config.
+   */
   themeConfig?: DeepPartial<ThemeConfig>
 }
 
+/**
+ * The labels of custom containers and GitHub-style alerts.
+ */
 export interface ContainerOptions {
+  /**
+   * The label of `::: info` containers.
+   * @default 'INFO'
+   */
   infoLabel?: string
+  /**
+   * The label of `> [!NOTE]` alerts.
+   * @default 'NOTE'
+   */
   noteLabel?: string
+  /**
+   * The label of `::: tip` containers.
+   * @default 'TIP'
+   */
   tipLabel?: string
+  /**
+   * The label of `::: warning` containers.
+   * @default 'WARNING'
+   */
   warningLabel?: string
+  /**
+   * The label of `::: danger` containers.
+   * @default 'DANGER'
+   */
   dangerLabel?: string
+  /**
+   * The label of `::: details` containers.
+   * @default 'Details'
+   */
   detailsLabel?: string
+  /**
+   * The label of `> [!IMPORTANT]` alerts.
+   * @default 'IMPORTANT'
+   */
   importantLabel?: string
+  /**
+   * The label of `> [!CAUTION]` alerts.
+   * @default 'CAUTION'
+   */
   cautionLabel?: string
   /**
    * Additional containers to register, mapping the container name to its
@@ -230,6 +461,9 @@ export interface ContainerOptions {
   customContainers?: Record<string, string>
 }
 
+/**
+ * The strings used by the copy button in code blocks.
+ */
 export interface CodeCopyButtonOptions {
   /**
    * The tooltip (`title` attribute) of the copy button in code blocks.
@@ -260,63 +494,114 @@ export interface MarkdownLocaleOptions {
   codeCopyButton?: CodeCopyButtonOptions
 }
 
+/**
+ * The locale configs of the site, keyed by locale directory
+ * (`'root'` for the default locale).
+ */
 export type LocaleConfig<ThemeConfig = any> = Record<
   string,
   LocaleSpecificConfig<ThemeConfig> & {
+    /**
+     * The label of the locale in the locale menu.
+     */
     label: string
+    /**
+     * The link of the locale menu item. Defaults to the locale directory.
+     */
     link?: string
+    /**
+     * The markdown strings of the locale.
+     */
     markdown?: MarkdownLocaleOptions
   }
 >
 
+/**
+ * Config overrides applied to a page on top of its locale config.
+ */
 export type AdditionalConfig<ThemeConfig = any> =
   LocaleSpecificConfig<ThemeConfig>
 
+/**
+ * Additional configs keyed by the directory they apply to (e.g. `/guide/`).
+ */
 export type AdditionalConfigDict<ThemeConfig = any> = Record<
   string,
   AdditionalConfig<ThemeConfig>
 >
 
+/**
+ * Resolves the additional configs of a page from its relative path, ordered
+ * from highest to lowest priority.
+ */
 export type AdditionalConfigLoader<ThemeConfig = any> = (
   relativePath: string
 ) => AdditionalConfig<ThemeConfig>[] | void
 
 // Manually declaring all properties as rollup-plugin-dts
 // is unable to merge augmented module declarations
+/**
+ * The environment object passed to `markdown-it` when rendering a page.
+ */
 export interface MarkdownEnv {
   /**
-   * The raw Markdown content without frontmatter
+   * The raw markdown content, with the frontmatter stripped.
    */
   content?: string
   /**
-   * The excerpt that extracted by `@mdit-vue/plugin-frontmatter`
-   *
-   * - Would be the rendered HTML when `renderExcerpt` is enabled
-   * - Would be the raw Markdown when `renderExcerpt` is disabled
+   * The excerpt extracted by `@mdit-vue/plugin-frontmatter`, rendered as
+   * HTML when excerpt rendering is enabled and kept as raw markdown
+   * otherwise.
    */
   excerpt?: string
   /**
-   * The frontmatter that extracted by `@mdit-vue/plugin-frontmatter`
+   * The frontmatter extracted by `@mdit-vue/plugin-frontmatter`.
    */
   frontmatter?: Record<string, unknown>
   /**
-   * The headers that extracted by `@mdit-vue/plugin-headers`
+   * The headers extracted by `@mdit-vue/plugin-headers`.
    */
   headers?: Header[]
   /**
-   * SFC blocks that extracted by `@mdit-vue/plugin-sfc`
+   * The SFC blocks extracted by `@mdit-vue/plugin-sfc`.
    */
   sfcBlocks?: MarkdownSfcBlocks
   /**
-   * The title that extracted by `@mdit-vue/plugin-title`
+   * The title extracted by `@mdit-vue/plugin-title`.
    */
   title?: string
+  /**
+   * The absolute path of the page, with rewrites applied.
+   */
   path: string
+  /**
+   * The path of the page relative to the source directory, with rewrites
+   * applied.
+   */
   relativePath: string
+  /**
+   * Whether clean URLs are enabled.
+   */
   cleanUrls: boolean
+  /**
+   * The URLs of the links collected from the page for the dead link check.
+   */
   links?: string[]
+  /**
+   * The line numbers at which each of `links` appears in the source.
+   */
   linkLines?: number[]
+  /**
+   * The absolute paths of the files inlined via `<!--@include-->`.
+   */
   includes?: string[]
+  /**
+   * The absolute path of the actual source file on disk: the route template
+   * for dynamic routes, or the original file when rewrites are in use.
+   */
   realPath?: string
+  /**
+   * The key of the locale the page belongs to.
+   */
   localeIndex?: string
 }