API reference

Every export, option, and data file the plugin ships.

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.

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

Parameters

PropType

contextLoadContext

Docusaurus load context; siteDir anchors dataFile and baseUrl prefixes infoUrl.

TypeLoadContext

optionsPluginOptions

Plugin options, after validateOptions.

TypePluginOptions

Returns Plugin: The Docusaurus plugin instance.

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.

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

Parameters

PropType

{ options }{ options: unknown }

The raw options from docusaurus.config.js.

Type{ options: unknown }

Returns PluginOptions: The options with every default applied.

PluginOptions

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

PropType

dataFile?string

Path to the names JSON your index generator writes, relative to the site directory. Shape: {ids: string[], bases?: Record<string, string[]>, version?: string}.

Typestring

Default'static/quickinfo/names.json'

infoUrl?string

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.

Typestring

Default'/quickinfo/info.json'

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.

Typestring[]

Default[]

languages?string[]

Language modules to enable for code annotation. Built in: "python".

Typestring[]

Default['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.

Typestring[]

Default[]

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.

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

Parameters

PropType

{ children }{ children?: ReactNode }

What to render inside; the runtime renders nothing of its own.

Type{ children?: ReactNode }

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.

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

Parameters

PropType

options?RehypeQuickinfoOptions

Rehype pass options.

TypeRehypeQuickinfoOptions

Default{}

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.

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.

PropType

dataFile?string

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.

Typestring

Default'static/quickinfo/names.json'

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.

Typestring[]

Default[]

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/'].

TypeArray<string | RegExp>

Default[]

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.

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

Parameters

PropType

options?quickinfo.QuickinfoAstroOptions

Integration options.

Typequickinfo.QuickinfoAstroOptions

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

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().

PropType

namesUrl?string

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}.

Typestring

Default'/quickinfo/names.json'

infoUrl?string

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.

Typestring

Default'/quickinfo/info.json'

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.

Typestring[]

Default[]

languages?string[]

Language modules to enable for code annotation. Built in: "python".

Typestring[]

Default['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.

PropType

namesUrl?string

URL of the names JSON.

Typestring

Default'names.json' (next to the script)

infoUrl?string

URL of the info JSON.

Typestring

Default'info.json' (next to the script)

preferPrefixes?string

Comma-separated id prefixes that win a short-name collision, e.g. mypkg.,toolkit..

Typestring

Defaultnone

languages?string

Comma-separated language modules to enable. Built in: python.

Typestring

Default'python'

defaultLanguage?string

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.

Typestring

Defaultnone

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.

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.

initQuickinfo(config: QuickinfoClientConfig): Promise<void>

Parameters

PropType

configQuickinfoClientConfig

Where the data lives and what to annotate, with defaults applied.

TypeQuickinfoClientConfig

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.

PropType

namesUrlstring

URL the browser fetches the names JSON from.

Typestring

infoUrlstring

URL the runtime fetches the info JSON from.

Typestring

preferPrefixesstring[]

Id prefixes that win a short-name collision.

Typestring[]

languagesstring[]

Language modules to enable for code annotation.

Typestring[]

defaultLanguage?string

Language assumed for code blocks that carry no language marker.

Typestring

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.

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

Parameters

PropType

idsstring[]

Every documented symbol id, as full dotted names.

Typestring[]

basesRecord?Record<string, string[]>

Class id to its direct documented base class ids, for inherited-member lookups.

TypeRecord<string, string[]>

Default{}

preferPrefixes?string[]

Id prefixes that win a short-name collision.

Typestring[]

Default[]

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.

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

Parameters

PropType

codestring

The whole code block.

Typestring

indexSymbolIndex

The resolution index; constructor calls resolve against it.

TypeSymbolIndex

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.

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

Parameters

PropType

namestring

The dotted name as written, e.g. driver.CPU.

Typestring

aliasesRecord<string, string>

Local name to dotted path, from the snippet's imports.

TypeRecord<string, string>

indexSymbolIndex

The resolution index.

TypeSymbolIndex

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.

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

Parameters

PropType

indexSymbolIndex

The resolution index.

TypeSymbolIndex

classIdstring

The class the member is accessed on.

Typestring

memberstring

The member's bare name.

Typestring

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.

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

Parameters

PropType

textstring

The mention's text; a trailing () is ignored.

Typestring

indexSymbolIndex

The resolution index.

TypeSymbolIndex

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.

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

Parameters

PropType

hrefstring

The link's href as written.

Typestring

indexSymbolIndex

The resolution index.

TypeSymbolIndex

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.

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

Parameters

PropType

namestring

The dotted occurrence as written, e.g. config.name.

Typestring

aliasesRecord<string, string>

Local name to dotted path, from the snippet's imports.

TypeRecord<string, string>

localsRecord<string, string>

Local name to class id, inferred from constructor calls.

TypeRecord<string, string>

bindsSet<string>

Every name the snippet binds.

TypeSet<string>

indexSymbolIndex

The resolution index.

TypeSymbolIndex

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.

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

Parameters

PropType

linePrismToken[]

The line's prism tokens.

TypePrismToken[]

codestring

The whole code block, for import and binding context.

Typestring

languagestring | undefined

The code block's prism language tag.

Typestring | undefined

indexSymbolIndex

The resolution index.

TypeSymbolIndex

languages?string[]

The enabled language modules.

Typestring[]

Default['python']

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.

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

Parameters

PropType

languagestring | undefined

The code block's language tag, e.g. py.

Typestring | undefined

languages?string[]

The enabled language modules.

Typestring[]

Default['python']

Returns boolean.

packNames

Group a names JSON’s ids by parent.

packNames(names: NamesJson): PackedNames

Parameters

PropType

namesNamesJson

The names JSON.

TypeNamesJson

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

unpackNames

Expand a packed names JSON back to full dotted ids.

unpackNames(packed: PackedNames): NamesJson

Parameters

PropType

packedPackedNames

The packed form.

TypePackedNames

Returns NamesJson: The names JSON.

SymbolIndex

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

PropType

idsstring[]

All ids, in index order; the prose resolver scans them for suffixes.

Typestring[]

idSetSet<string>

Full dotted ids, e.g. "pathlib.Path".

TypeSet<string>

shortMapMap<string, string[]>

Final segment -> ids ending with it.

TypeMap<string, string[]>

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.

TypeMap<string, string | null>

membersMap<string, Map<string, string>>

Parent id -> (member name -> defining id), for documented parents only.

TypeMap<string, Map<string, string>>

basesMap<string, string[]>

Class id -> direct documented base class ids.

TypeMap<string, string[]>

memberMemoMap<string, string | undefined>

Memo for inherited-member lookups.

TypeMap<string, string | undefined>

preferPrefixesstring[]

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.

Typestring[]

SnippetContext

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

PropType

aliasesRecord<string, string>

Local name to dotted path, from import statements.

TypeRecord<string, string>

localsRecord<string, string>

Local name to class id, inferred from constructor-call bindings.

TypeRecord<string, string>

bindsSet<string>

Every name the snippet binds: assignments, parameters, as targets.

TypeSet<string>

PrismToken

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

PropType

typesstring[] | string

Prism token types; comment and string tokens are never annotated.

Typestring[] | string

contentstring

The token's source text.

Typestring

apiId?string

Set by annotateLines when the token resolves to an API symbol.

Typestring

NamesJson

The names JSON an index generator writes.

PropType

idsstring[]

Every documented symbol id, as full dotted names.

Typestring[]

bases?Record<string, string[]>

Class id to its direct documented base class ids.

TypeRecord<string, string[]>

version?string

Busts the info JSON's cache when the index changes.

Typestring

PackedNames

The names JSON with ids grouped by parent.

PropType

treeRecord<string, string[]>

Parent id ("" for top level) to its members' final segments.

TypeRecord<string, string[]>

bases?Record<string, string[]>

TypeRecord<string, string[]>

version?string

Typestring

Data files

The schemas of the names JSON and the info JSON are documented in index files.