---
title: API reference
description: Every export, option, and data file the plugin ships.
---

{/* Generated by scripts/gen-api.mjs from the JSDoc in src/. Edit the
    source comments, then run `npm run gen:api`. */}

Every export, option, and data file the plugin ships, generated from the
plugin's source. The hovers on this page run through the plugin's own
Astro integration, with the names JSON and info JSON generated from the
same source.

## Docusaurus plugin

Import from `quickinfo/docusaurus`.

### pluginQuickinfo

The Docusaurus plugin. Registers the theme components that annotate code blocks, aliases the packed names JSON and the runtime config into the client bundle, and mounts the hover runtime through `Root`. Prose mentions are annotated by the rehype pass, registered separately.

```ts
pluginQuickinfo(context: LoadContext, options: PluginOptions): Plugin
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `context` | `LoadContext` | - | Docusaurus load context; siteDir anchors dataFile and baseUrl prefixes infoUrl. |
| `options` | `PluginOptions` | - | Plugin options, after validateOptions. |

Returns `Plugin`: The Docusaurus plugin instance.

```js
module.exports = {
  plugins: [require.resolve('quickinfo/docusaurus')],
  presets: [
    [
      'classic',
      {
        docs: {
          rehypePlugins: [require('quickinfo/rehype')],
        },
      },
    ],
  ],
};
```

### validateOptions

Validates the plugin options and fills in defaults. Docusaurus calls it before `pluginQuickinfo`.

```ts
validateOptions({ options }: { options: unknown }): PluginOptions
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `{ options }` | `{ options: unknown }` | - | The raw options from docusaurus.config.js. |

Returns `PluginOptions`: The options with every default applied.

### PluginOptions

Options for the Docusaurus plugin, passed in `docusaurus.config.js`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `dataFile?` | `string` | `'static/quickinfo/names.json'` | Path to the names JSON your index generator writes, relative to the site directory. Shape: {ids: string[], bases?: Record<string, string[]>, version?: string}. |
| `infoUrl?` | `string` | `'/quickinfo/info.json'` | URL the runtime fetches the info JSON from, with ?v=<version> appended from the names JSON. A root-relative URL gets the site's baseUrl prefixed. |
| `preferPrefixes?` | `string[]` | `[]` | Id prefixes that win a short-name collision, e.g. ["mypkg."] on a site that indexes both its own package and Python stdlib ids. Keeps secondary id sources from changing existing annotations. |
| `languages?` | `string[]` | `['python']` | Language modules to enable for code annotation. Built in: "python". |
| `exclude?` | `string[]` | `[]` | Route prefixes whose code blocks stay unannotated, under the site's baseUrl: pages for another language or another version of the API than the index describes, e.g. ['/stable/', '/api/rust/']. Pass the same pages to the rehype pass's exclude. |

### QuickinfoRuntime

Import from `quickinfo/docusaurus/runtime`.

Starts the hover runtime and loads its styles. The plugin's `Root` mounts it; mount it yourself (around your layout) only when another plugin's `Root` replaces this one.

```ts
QuickinfoRuntime({ children }: { children?: ReactNode }): ReactNode
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `{ children }` | `{ children?: ReactNode }` | - | What to render inside; the runtime renders nothing of its own. |

Returns `ReactNode`.

## Rehype pass

Import from `quickinfo/rehype`.

### rehypeQuickinfo

The rehype pass. Stamps `data-api-id` onto prose mentions of API symbols at build time: inline code, and links to API pages. A mention annotates only when it resolves to one symbol; a link to an API page names its symbol even when the bare name is ambiguous.

```ts
rehypeQuickinfo(options?: RehypeQuickinfoOptions): (tree: Node, file?: PageFile) => void
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `options?` | `RehypeQuickinfoOptions` | `{}` | Rehype pass options. |

Returns `(tree: Node, file?: PageFile) => void`: The rehype transformer. It annotates nothing when `dataFile` is missing or empty, so a build before the index exists still passes.

```js
const quickinfoRehype = require('quickinfo/rehype');
const dataFile = path.resolve(__dirname, 'generated/quickinfo-names.json');

// In the docs plugin or preset options:
rehypePlugins: [[quickinfoRehype, { dataFile }]],
```

### RehypeQuickinfoOptions

Options for the rehype pass, passed in the markdown config.

| Prop | Type | Default | Description |
| - | - | - | - |
| `dataFile?` | `string` | `'static/quickinfo/names.json'` | Path to the names JSON your index generator writes. A relative path resolves against the site directory (the nearest folder above each page holding a docusaurus.config.*), the same base the plugin uses. |
| `preferPrefixes?` | `string[]` | `[]` | Id prefixes that win a short-name collision, e.g. ["mypkg."] on a site that indexes both its own package and Python stdlib ids. |
| `exclude?` | `Array<string \| RegExp>` | `[]` | Pages to leave unannotated: a string matches when the page's source path contains it, a RegExp when it matches the path. Use it for reference pages of another language or another version of the API than the index describes, e.g. ['/api/rust/', 'versioned_docs/']. |

## Astro integration

Import from `quickinfo/astro`.

### quickinfo

The Astro integration, for Blume and plain Astro sites. Injects one script on every page that fetches the names JSON, stamps `data-api-id` onto prose mentions and Python code blocks in the DOM, and wires the tooltip. Annotation runs in the browser, so it works with any Markdown processor and behaves the same in dev and production.

```ts
quickinfo(options?: quickinfo.QuickinfoAstroOptions): quickinfo.QuickinfoIntegration
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `options?` | `quickinfo.QuickinfoAstroOptions` | - | Integration options. |

Returns `quickinfo.QuickinfoIntegration`: The Astro integration to add to `integrations`.

```ts
import quickinfo from 'quickinfo/astro';
import { defineConfig } from 'astro/config';

// Serves public/quickinfo/names.json and info.json; no options needed.
export default defineConfig({
  integrations: [quickinfo()],
});
```

### QuickinfoAstroOptions

Options for the Astro integration, passed to `quickinfo()`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `namesUrl?` | `string` | `'/quickinfo/names.json'` | URL the browser fetches the names JSON from. A root-relative URL gets the site's base prefixed. Shape: {ids: string[], bases?: Record<string, string[]>, version?: string}. |
| `infoUrl?` | `string` | `'/quickinfo/info.json'` | URL the runtime fetches the info JSON from, with ?v=<version> appended from the names JSON. A root-relative URL gets the site's base prefixed. |
| `preferPrefixes?` | `string[]` | `[]` | Id prefixes that win a short-name collision, e.g. ["mypkg."] on a site that indexes both its own package and Python stdlib ids. |
| `languages?` | `string[]` | `['python']` | Language modules to enable for code annotation. Built in: "python". |

## Standalone script

The script for Sphinx, MkDocs, and any other static site, shipped as `quickinfo/browser` and copied next to its data by the CLI. Options are data attributes on its script tag.

### ScriptAttributes

Options for the standalone script, set as data attributes on its `<script>` tag (`data-names-url`, `data-prefer-prefixes`, ...). Relative URLs resolve against the script's own URL.

| Prop | Type | Default | Description |
| - | - | - | - |
| `namesUrl?` | `string` | `'names.json' (next to the script)` | URL of the names JSON. |
| `infoUrl?` | `string` | `'info.json' (next to the script)` | URL of the info JSON. |
| `preferPrefixes?` | `string` | `none` | Comma-separated id prefixes that win a short-name collision, e.g. mypkg.,toolkit.. |
| `languages?` | `string` | `'python'` | Comma-separated language modules to enable. Built in: python. |
| `defaultLanguage?` | `string` | `none` | Language assumed for code blocks with no language marker. Set it to python when the highlighter emits no language class; on MkDocs, enable pymdownx.highlight's pygments_lang_class instead. |

## CLI

Builds hover data from a built Sphinx or MkDocs (mkdocstrings) site: ids, kinds, and links from `objects.inv`, and signatures, summaries, and base classes from the API pages.

```text
Usage:
  quickinfo build <site-dir> [--out <dir>] [--served-at <path>] [--inventory <file>] [--no-assets]
  quickinfo assets <dir>

build   Write names.json, info.json, and quickinfo.js for a built Sphinx or
        MkDocs (mkdocstrings) site, from its objects.inv and API pages.
        --out        Output directory. Default: <site-dir>/_static/quickinfo
                     when _static exists (Sphinx), else <site-dir>/quickinfo.
        --served-at  Where the output is served, relative to the site root.
                     Default: --out's path inside <site-dir>, or its folder
                     name when --out is outside the site (a docs folder the
                     generator copies to the root, like docs/quickinfo).
        --inventory  The objects.inv to read. Default: <site-dir>/objects.inv.
        --no-assets  Skip copying quickinfo.js.
assets  Copy quickinfo.js into <dir>.
```

## Browser runtime

What the Astro integration and the standalone script run on every page. Sites reach it through those adapters.

### initQuickinfo

Boot the runtime: load the names JSON, annotate the current document, wire the hover listeners, and keep annotating as the page changes. A second call is a no-op.

```ts
initQuickinfo(config: QuickinfoClientConfig): Promise<void>
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `config` | `QuickinfoClientConfig` | - | Where the data lives and what to annotate, with defaults applied. |

Returns `Promise<void>`: Resolves once the first annotation pass is done, or right away when the names JSON can't be loaded.

### QuickinfoClientConfig

The resolved config the browser entry receives.

| Prop | Type | Default | Description |
| - | - | - | - |
| `namesUrl` | `string` | - | URL the browser fetches the names JSON from. |
| `infoUrl` | `string` | - | URL the runtime fetches the info JSON from. |
| `preferPrefixes` | `string[]` | - | Id prefixes that win a short-name collision. |
| `languages` | `string[]` | - | Language modules to enable for code annotation. |
| `defaultLanguage?` | `string` | - | Language assumed for code blocks that carry no language marker. |

## Resolution engine

Import from `quickinfo`.

Pure functions over the index that `buildIndex` returns, shared by every adapter: the Docusaurus theme components, the rehype pass, and the browser annotator.

### buildIndex

Builds the resolution index from the names JSON's fields.

```ts
buildIndex(ids: string[], basesRecord?: Record<string, string[]>, preferPrefixes?: string[]): SymbolIndex
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `ids` | `string[]` | - | Every documented symbol id, as full dotted names. |
| `basesRecord?` | `Record<string, string[]>` | `{}` | Class id to its direct documented base class ids, for inherited-member lookups. |
| `preferPrefixes?` | `string[]` | `[]` | Id prefixes that win a short-name collision. |

Returns `SymbolIndex`: The index every resolver takes.

### getSnippetContext

The binding context (imports, inferred locals, bound names) for a Python snippet, parsed once and memoized no matter how many times the snippet's pieces are resolved. The DOM annotator consumes this on Astro/Blume sites, where there is no prism token stream to carry it.

```ts
getSnippetContext(code: string, index: SymbolIndex): SnippetContext
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `code` | `string` | - | The whole code block. |
| `index` | `SymbolIndex` | - | The resolution index; constructor calls resolve against it. |

Returns `SnippetContext`.

### resolveApiName

Resolve a dotted name against the index using import aliases first, then a unique global short name. Ambiguous names resolve to undefined and stay cold: the mention renders without an id.

```ts
resolveApiName(name: string, aliases: Record<string, string>, index: SymbolIndex): string | undefined
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | - | The dotted name as written, e.g. driver.CPU. |
| `aliases` | `Record<string, string>` | - | Local name to dotted path, from the snippet's imports. |
| `index` | `SymbolIndex` | - | The resolution index. |

Returns `string | undefined`: The symbol id, or `undefined` when the name is unknown or ambiguous.

### resolveMember

Find a member's defining id on a class, walking the documented base classes when the class doesn't define the member itself: `name` accessed on a `Path` resolves to `pathlib.PurePath.name`. Memoized with a pre-set undefined result as the cycle guard.

```ts
resolveMember(index: SymbolIndex, classId: string, member: string): string | undefined
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `index` | `SymbolIndex` | - | The resolution index. |
| `classId` | `string` | - | The class the member is accessed on. |
| `member` | `string` | - | The member's bare name. |

Returns `string | undefined`: The defining id, or `undefined` when no class in the chain documents the member.

### resolveProseMention

Resolve a prose mention of a symbol against the index: an exact dotted name, a unique dotted suffix, or a globally-unique bare name (with the preferred prefix breaking ties). Anything else stays cold. Shared by the rehype pass (build time, Docusaurus) and the DOM annotator (browser time, Astro/Blume), which must resolve mentions identically.

```ts
resolveProseMention(text: string, index: SymbolIndex): string | undefined
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `text` | `string` | - | The mention's text; a trailing () is ignored. |
| `index` | `SymbolIndex` | - | The resolution index. |

Returns `string | undefined`: The symbol id, or `undefined` when the mention is unknown or ambiguous.

### resolveHref

Extract a symbol id from a link to an API page on the same site. A fragment naming a symbol wins (`pathlib.html#pathlib.Path`, the shape Sphinx and mkdocstrings emit); otherwise the page path's last segment names it when it reads as a symbol page: a dotted id (`pathlib.Path/`) or a Markdown file (`Path.md`). A plain path segment (`/quickinfo/`, a site's own base path) is a page, not a symbol. Links with a scheme or host (`https://docs.python.org/...#int`) point at another site's symbols and never resolve, and only ids in the index count.

```ts
resolveHref(href: string, index: SymbolIndex): string | undefined
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `href` | `string` | - | The link's href as written. |
| `index` | `SymbolIndex` | - | The resolution index. |

Returns `string | undefined`: The symbol id, or `undefined` for any other link.

### resolveDotted

Resolve a dotted occurrence for annotation. Import aliases resolve as in resolveApiName; inferred local variables resolve member access through the inheritance chain, so `config.name` annotates as `pathlib.PurePath.name` once `config = Path("app.toml")` is seen. Any other name bound in the snippet stays cold: it's the user's variable, not an API mention, even when it matches a unique short name.

```ts
resolveDotted(name: string, aliases: Record<string, string>, locals: Record<string, string>, binds: Set<string>, index: SymbolIndex): string | undefined
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | - | The dotted occurrence as written, e.g. config.name. |
| `aliases` | `Record<string, string>` | - | Local name to dotted path, from the snippet's imports. |
| `locals` | `Record<string, string>` | - | Local name to class id, inferred from constructor calls. |
| `binds` | `Set<string>` | - | Every name the snippet binds. |
| `index` | `SymbolIndex` | - | The resolution index. |

Returns `string | undefined`: The symbol id, or `undefined` when the occurrence stays cold.

### annotateLines

Annotate one prism-rendered line of tokens: each identifier piece gets `apiId` when it resolves against the index, so `dumps` in `json.dumps()` resolves to `json.dumps` once `import json` is seen, and `name` in `config.name` resolves to the inherited `pathlib.PurePath.name` once `config = Path("app.toml")` is. Returns a new array; never mutates the input.

```ts
annotateLines(line: PrismToken[], code: string, language: string | undefined, index: SymbolIndex, languages?: string[]): PrismToken[]
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `line` | `PrismToken[]` | - | The line's prism tokens. |
| `code` | `string` | - | The whole code block, for import and binding context. |
| `language` | `string \| undefined` | - | The code block's prism language tag. |
| `index` | `SymbolIndex` | - | The resolution index. |
| `languages?` | `string[]` | `['python']` | The enabled language modules. |

Returns `PrismToken[]`: The line's tokens with `apiId` set on resolved identifiers.

### isAnnotatedLanguage

Whether code blocks in a prism language get annotated: the language has a built-in module and is enabled in the `languages` option.

```ts
isAnnotatedLanguage(language: string | undefined, languages?: string[]): boolean
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `language` | `string \| undefined` | - | The code block's language tag, e.g. py. |
| `languages?` | `string[]` | `['python']` | The enabled language modules. |

Returns `boolean`.

### packNames

Group a names JSON's ids by parent.

```ts
packNames(names: NamesJson): PackedNames
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `names` | `NamesJson` | - | The names JSON. |

Returns `PackedNames`: The packed form, with `bases` and `version` carried over.

### unpackNames

Expand a packed names JSON back to full dotted ids.

```ts
unpackNames(packed: PackedNames): NamesJson
```

#### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `packed` | `PackedNames` | - | The packed form. |

Returns `NamesJson`: The names JSON.

### SymbolIndex

The resolution index built from the names JSON. Every resolver takes one; build it with `buildIndex`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `ids` | `string[]` | - | All ids, in index order; the prose resolver scans them for suffixes. |
| `idSet` | `Set<string>` | - | Full dotted ids, e.g. "pathlib.Path". |
| `shortMap` | `Map<string, string[]>` | - | Final segment -> ids ending with it. |
| `suffixes?` | `Map<string, string \| null>` | - | Dotted suffix (two or more segments) -> the one id ending with it, or null when several ids share the suffix. Built on the first prose lookup: code annotation never needs it. |
| `members` | `Map<string, Map<string, string>>` | - | Parent id -> (member name -> defining id), for documented parents only. |
| `bases` | `Map<string, string[]>` | - | Class id -> direct documented base class ids. |
| `memberMemo` | `Map<string, string \| undefined>` | - | Memo for inherited-member lookups. |
| `preferPrefixes` | `string[]` | - | Id prefixes that win a short-name collision (e.g. "mypkg." for a site that indexes its own package and Python stdlib ids), so extra id sources can never change an existing annotation. |

### SnippetContext

A Python snippet's binding structure, parsed once per snippet.

| Prop | Type | Default | Description |
| - | - | - | - |
| `aliases` | `Record<string, string>` | - | Local name to dotted path, from import statements. |
| `locals` | `Record<string, string>` | - | Local name to class id, inferred from constructor-call bindings. |
| `binds` | `Set<string>` | - | Every name the snippet binds: assignments, parameters, as targets. |

### PrismToken

One prism token on a rendered code line, as theme-classic passes it.

| Prop | Type | Default | Description |
| - | - | - | - |
| `types` | `string[] \| string` | - | Prism token types; comment and string tokens are never annotated. |
| `content` | `string` | - | The token's source text. |
| `apiId?` | `string` | - | Set by annotateLines when the token resolves to an API symbol. |

### NamesJson

The names JSON an index generator writes.

| Prop | Type | Default | Description |
| - | - | - | - |
| `ids` | `string[]` | - | Every documented symbol id, as full dotted names. |
| `bases?` | `Record<string, string[]>` | - | Class id to its direct documented base class ids. |
| `version?` | `string` | - | Busts the info JSON's cache when the index changes. |

### PackedNames

The names JSON with ids grouped by parent.

| Prop | Type | Default | Description |
| - | - | - | - |
| `tree` | `Record<string, string[]>` | - | Parent id ("" for top level) to its members' final segments. |
| `bases?` | `Record<string, string[]>` | - | |
| `version?` | `string` | - | |

## Data files

The schemas of the names JSON and the info JSON are documented in
[index files](/quickinfo/index-files).