API reference

CodeBlocks(; languages=["julia"], reference_links=true, popups=true, line_numbers=true, repl_line_numbers=true, min_lines=1, line_counter=:restart)

Documenter plugin that enhances code blocks with syntax highlighting, line numbers / linkable lines, and reference links — all in a single pass. Julia is highlighted locally with JuliaSyntax (including julia-repl/jldoctest blocks), so no node/prerender is needed.

• languages: which code-block languages to process.
• reference_links: wrap identifiers that name a documented object in a link to its docstring. Macro names link too. Names in binding positions — left of =, function parameters, loop variables, … — are not uses and never link.
• popups: doxygen-style hover tooltips on reference links, embedded per page (no fetching): the target's signature and the docstring's first sentence. When a reference matches several documented methods (a bare identifier, a splatted call, …) the tooltip instead lists all candidate signatures to pick from. Requires reference_links=true.
• line_numbers: add the line-number gutter + linkable lines. When false, blocks are still highlighted (and linked) but rendered without a gutter.
• repl_line_numbers: also add the gutter to REPL transcripts (julia-repl blocks and REPL-style jldoctests). Requires line_numbers=true.
• min_lines: blocks with fewer lines get an id + permalink but no gutter (the default numbers every block, including one-liners).
• line_counter: the default line-counter mode for every page — :restart, :continue, or :named (see the @codeblocks block below, which overrides it per page, positionally).

Reference resolution follows the page's @meta CurrentModule positionally, exactly like @ref: the module in effect at a block's position applies to that block, and code blocks inside a docstring resolve in the docstring's own module.

Pages can configure the plugin locally with an @codeblocks block:

```@codeblocks
line_counter = :continue
```

• line_counter: :restart (default) numbers every block from 1; :continue carries one running line counter across the page's code blocks (julia, julia-repl, executed @repl), tutorial-style; :named keeps one counter per named series — blocks sharing a name (@example name, @repl name, jldoctest name, or a second fence token like `julia name) continue each other, while unnamed blocks restart. Like @meta, the setting applies from its position to the end of the page (or the next @codeblocks block). Blocks inside docstrings are their own page: they always start at 1 and do not advance any counter.

The first code block of a docstring — the signature header — gets no line numbers or permalink (headers aren't always valid Julia, e.g. f(x[, y])), but the argument and return types in it link to their docstrings; the documented name itself and the parameter names stay plain. Throughout a docstring, references with the enclosing docstring among their candidate targets are not linked — the reader is already there — while calls whose arity resolves to a different documented method still link.

Build warnings prefixed CodeBlocks: nudge toward tooltip-friendly (and generally better) docstrings: they fire — once per problem, and only for docstrings some code block references — when a docstring lacks a leading signature block or a prose first sentence, when the first sentence exceeds 200 characters, and when a call's arity matches no documented method.

Pass to makedocs(plugins=[CodeBlocks()]).

greet()

Print a friendly greeting to standard output. A minimal documented function for exercising reference links from code blocks.

Examples

A julia-repl block inside a docstring:

julia> greet()Hello World!

A script-style jldoctest whose output is NOT valid Julia (and contains the documented name foo) — to see how the highlighter copes:

println("foo bar baz")# outputfoo bar baz

add_numbers(a, b)

Return the sum of a and b. A trivial documented function used in the docs testbed to verify that identifiers in code blocks link to their docstrings.

Examples

A plain julia block (gets highlighting, line numbers, and reference links — note foo links to its docstring):

x = add_numbers(1, 2)y = add_numbers(x, foo(10))

A jldoctest block (executed and checked by Documenter):

julia> add_numbers(2, 3)5julia> add_numbers(add_numbers(1, 2), 3)6

A julia-repl block with a multi-line input (the whole function … end definition is one input, highlighted together):

julia> function describe(a, b)           s = add_numbers(a, b)           return "sum is $s"       enddescribe (generic function with 1 method)julia> describe(2, 3)"sum is 5"

MyType

A documented type used to check that type identifiers in code blocks resolve to their docstring anchors.

Examples

julia> MyType(3)MyType(3)julia> MyType(3).x3

foo(a)

The one-argument method of foo. Has its own docstring, separate from foo(a, b), to test how links resolve for functions with multiple documented methods.

Examples

A script-style jldoctest (code, then # output, then the expected result):

values = [foo(i) for i in 1:3]total = add_numbers(values[1], values[3])# output4

foo(a, b)

The two-argument method of foo, with its own docstring separate from foo(a).

Examples

julia> foo(10, 20)30julia> foo(1)1

The two-argument call above is a self reference (not linked); the one-argument call resolves to the other method's docstring and links.

qux(x::Int)

Double an integer. Same-arity sibling of qux(x::String) — the two methods differ only in argument type, which a call site like qux(1) cannot disambiguate (we only extract arity), so references to qux list both.

qux(x::String)

Repeat a string. See qux(x::Int) for the same-arity integer method.

transform(v::AbstractVector{T}, f::Function = identity; rev::Bool = false) where {T}

Apply f to each element of v, optionally reversing the result. The signature exercises type annotations, a parametric container, a default argument, a keyword argument, and a where clause in the hover tooltip.

measure(x::Int)

Measure an integer. One of six documented methods of measure, together stress-testing long disambiguation lists.

measure(x::Float64)

Measure a float, rounding to the nearest integer.

measure(x::String)

Measure a string by its length.

measure(x, y)

Measure two things together.

measure(x, y, z; scale::Real = 1)

Measure three things, scaled.

measure()

Measure nothing at all. The 0-argument method: excluded from disambiguation lists whenever the call site guarantees at least one positional argument, even via a splat like measure(x, rest...).

combine(a, b)

Combine two things. combine is included in the docs with a bare @docs DocumenterCodeBlocks.combine entry (no signature), so this docstring and the three-argument one render aggregated inside one docstring <details> — but each docstring still gets its own <section><div>, so both signature headers receive the header treatment (highlight only).

combine(a, b, c)

Combine three things. The second docstring of the aggregated combine entry; its signature header must be stripped of gutter/links just like the first.

process(data::AbstractMatrix{<:Real}, weights::AbstractVector{<:Real};
        normalize::Bool = true, atol::Real = 1e-8,
        callback::Union{Function, Nothing} = nothing) -> AbstractMatrix

Process a data matrix with per-column weights. The signature block spans several lines, stress-testing the tooltip layout for long headers.

process(data::AbstractVector{<:Real}; normalize::Bool = true, atol::Real = 1e-8)

Process a single data vector. Long single-line signature header, and the same-name sibling of the matrix method above.

clone(m::MyType; deep::Bool = false) -> MyType

Return a copy of m. The signature header above references the documented type MyType twice — as the argument annotation and as the -> return type — and both mentions link, while the parameter names and clone itself stay plain.

@twice(expr)

Evaluate expr twice and return the value of the second evaluation. A documented macro: macro names in code blocks link to their docstring.

w"text"

Return text unchanged. A documented string macro: the w prefix of a w"…" literal links to this docstring.