Reference links

Identifiers in code blocks that name a documented object become links to the docstring — the code-block equivalent of Documenter's @ref. Resolution uses the same machinery and the page's CurrentModule meta, so a code block and an @ref link always agree on the target. CurrentModule applies positionally, exactly as it does for @ref: a page can switch modules with a second @meta block halfway down, and each code block resolves in the module in effect at its own position. Code blocks inside a docstring resolve in the docstring's own module, wherever the docstring is spliced.

function demo(m::MyType)    t = MyType(3)    s = add_numbers(t.x, m.x)    greet()    return undocumented_helper(s)end

Hover (or click) MyType, add_numbers, and greet above — and note that undocumented_helper stays plain text: names that don't resolve are left alone, silently.

Links attach to call callees (add_numbers(...)), type positions (m::MyType), and plain value mentions — a documented name used as a function argument, on the right of =, in a condition, and so on, like zero(MyType) or a documented constant. What never links is a binding: a name to the left of =, a function parameter, a loop variable — there the name is not a use of the documented object (in the block above, the parameter m binds and stays plain):

a = foo(1)      # links the foo(a) docstringb = foo(1, 2)   # links the foo(a, b) docstringc = foo         # value mention → links, listing both methodsd = DocumenterCodeBlocks.foo(1)   # qualified callfoo = c         # binding (left of =) → no link

As the block above shows, resolution is arity-aware: a call with n positional arguments links to the method documented with n arguments, not just to the first documented method. Qualified names resolve as a whole, but the link attaches to the name itself — the module qualifier and dot stay outside.

Macro calls link on their name. No syntactic vouching is needed there: unlike a bare identifier, a macro name can only ever mean the macro.

@twice greet()                       # unqualified macro nameDocumenterCodeBlocks.@twice greet()  # qualified names = w"hello"                         # string macro

Code blocks inside docstrings get reference links too, with one exception: a reference with the enclosing docstring among its candidate targets is left unlinked — it (possibly) means the very thing the reader is looking at. A call whose arity resolves to a different documented method still links, so an example in foo(a, b)'s docstring that calls foo(1) links to foo(a). The signature header — a docstring's leading code block — links its argument and return types the same way (see clone's header in the API reference, which links MyType twice), while the documented name and the parameters stay plain.

Hover tooltips

Every reference link has a doxygen-style hover tooltip showing the target's signature and the first sentence of its docstring. Tooltips are embedded in the page at build time and work offline.

When a reference is ambiguous — several documented methods match — the tooltip lists all candidate signatures instead; hovering an entry previews its documentation and clicking navigates to it:

foo(args...)       # splat: positional count unknown → both methods listedq = qux(1)         # same arity as qux("…") → both typed signatures listedy = add_numbers(1, 2)  # single documented method → plain tooltip

Arity pruning

Candidate lists only show methods that can actually take the call's argument count. measure has six documented methods:

m = measure(args...)               # pure splat → all six methods listedml = measure(1, args...)           # at least 1 argument → the 0-argument method drops outm1 = measure(1)                    # arity 1 → only the three 1-argument methodsm2 = measure(1, 2)                 # untyped (x, y) → exact match, single tooltip

Aggregated docstrings

A bare @docs entry aggregates all of a function's docstrings under one anchor. Tooltips are arity-matched within the aggregate: a call site with a known argument count shows only the matching method's signature and summary, while an unknown count shows all signature headers:

c2 = combine(1, 2)      # arity 2 → only combine(a, b) shownc3 = combine(1, 2, 3)   # arity 3 → only combine(a, b, c) showncs = combine(args...)   # unknown arity → both signature headers shown

Long signatures

Tooltips render multi-line signature headers verbatim and size to fit:

p = process(rand(3))               # arity prunes to the vector methodP = process(rand(3, 3), ones(3))   # arity 2 → the multi-line matrix signaturet = transform([1, 2, 3], sqrt; rev = true)

Configuration

• reference_links = false turns linking off entirely,
• popups = false keeps the links but disables the tooltips.

Both are keyword arguments of CodeBlocks.