# DocumenterCodeBlocks.jl announcement

**URL:** <https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552>\
**Category:** Package Announcements\
**Tags:** documentation, documenter\
**Created:** [July 31, 2026, 6:27pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552 "2026-07-31T18:27:40Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [July 31, 2026, 6:27pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/1 "2026-07-31T18:27:40Z")

</div>

I want to to announce [DocumenterCodeBlocks.jl](https://github.com/fredrikekre/DocumenterCodeBlocks.jl), a [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) plugin that makes the code blocks in your package documentation quite a bit more interesting. To enable it the only thing you have to change is to pass the `CodeBlocks()` to `Documenter.makedocs`:

```julia
using Documenter, DocumenterCodeBlocks

makedocs(
    # ...
    plugins = [CodeBlocks()],
)

```

I think that the defaults are good, but some things can be configured by passing keyword arguments to the constructor, see [the documentation](https://fredrikekre.github.io/DocumenterCodeBlocks.jl/api/).

The best way to get a feel for it is the [documentation itself](https://fredrikekre.github.io/DocumenterCodeBlocks.jl/). Every code block there is rendered by the plugin, so hover, click, and select away. Here is what you get:

## Reference links and hover tooltips

Identifiers in code blocks that name a documented object become links to their docstring. Resolution is call-arity aware: `foo(1, 2)` links to the `foo(a, b)` method documentation, not just to “some docstring for `foo`”. Every link also gets a doxygen-style hover tooltip with the target’s signature and a one-line summary:

![tooltips](https://global.discourse-cdn.com/julialang/original/3X/1/a/1a2cae96b243ca00d79bf77c06257cf31b23e5f6.gif)

Links only attach where the syntax vouches for the meaning (call callees like `add_numbers(...)` and type positions like `m::MyType`) and names that don’t resolve are silently left alone. For ambiguous references, e.g. a splatted call `measure(args...)` that could hit several methods, the tooltip shows the “arity-pruned” candidate list instead, as seen at the end of the clip above.

## Line numbers and linkable lines

Every code block gets GitHub-style line numbers with a content-addressed permalink. Clicking the gutter selects a line, shift-click or drag selects a range, and the selection is reflected in the URL as a stable fragment like `#c-1a2b3c4d-L5-L11`. Selections survive reload and scroll into view on page load.

![linenumbers](https://global.discourse-cdn.com/julialang/original/3X/8/0/80dc3d791d58b0f0d7920cd9cbcab2bcf006573c.gif)

The copy code block button is unaffected, the gutter numbers never end up in your clipboard.

## Build-time syntax highlighting with JuliaSyntax

Julia code blocks are highlighted at build time using [JuliaSyntax.jl](https://github.com/JuliaLang/JuliaSyntax.jl) instead of highlight.js’s regex approximation. This means correct handling of the tricky cases (nested string interpolation, command literals, type parameters, word operators, etc) and more granularity. Works for `julia`, `julia-repl`, `jldoctest`, and executed `@repl` blocks (including their ANSI-colored output):

 ![highlight-mocha](https://global.discourse-cdn.com/julialang/original/3X/b/e/be081043a0aaae54870015700aedad14ba7766c0.png)

The screenshot is using the catppuccin-mocha theme but all six default Documenter themes are supported.

## Docstring-quality warnings

The tooltips are only as good as the docstrings they summarize, so the plugin can optionally warn when a docstring is missing a leading signature block or a short first sentence.

## Installation

```julia-repl
julia> import Pkg

julia> Pkg.add("DocumenterCodeBlocks")

```

## Status and caveats

The plugin necessarily builds on some Documenter internals beyond the documented plugin API so there might have to be updates to this package for new Documenter releases. If you maintain docs for a package, I’d love for you to try it out and report anything that breaks. Feedcback, issues and PRs are very welcome!

Thanks!

---

<div class="post-metadata">

**Author:** ![cormullion](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/cormullion/32/49131_2.png) [@cormullion](https://discourse.julialang.org/u/cormullion)\
**Post date:** [August 1, 2026, 10:19am UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/2 "2026-08-01T10:19:31Z")

</div>

This is great - thanks! Even my code looks pretty good now!

I noticed that nearly every function call is underlined. It’s almost becoming visually distracting…

 ![Screenshot 2026-08-01 at 11.14.30](https://global.discourse-cdn.com/julialang/original/3X/2/2/2224ad21e1ec412c26ba3f9f3a967ade801dc3ac.png)

I think a subtler visual style would work just as well - perhaps it could be arranged such that the underlining is less noticeable, and/or activated only when the focus is in the code-block? Or make the underlining get brighter as your pointer gets nearer? 🙂

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [August 1, 2026, 10:23am UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/3 "2026-08-01T10:23:10Z")

</div>

Yea maybe just a different color for links would be better.

---

<div class="post-metadata">

**Author:** ![cormullion](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/cormullion/32/49131_2.png) [@cormullion](https://discourse.julialang.org/u/cormullion)\
**Post date:** [August 2, 2026, 4:59pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/4 "2026-08-02T16:59:22Z")

</div>

Thanks for making this improvement happen so quickly!

 ![Screenshot 2026-08-02 at 18.02.53|560](https://global.discourse-cdn.com/julialang/original/3X/4/c/4ce3caabe71e4693a755d18b6e1c2beb84de9a21.png)

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [August 2, 2026, 5:25pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/5 "2026-08-02T17:25:20Z")

</div>

Yea, toned it down a bit in the new release. Thanks for the feedback!

---

<div class="post-metadata">

**Author:** ![j-fu](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/j-fu/32/11373_2.png) [@j-fu](https://discourse.julialang.org/u/j-fu)\
**Post date:** [August 2, 2026, 8:49pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/6 "2026-08-02T20:49:56Z")

</div>

Does the package play together with DocumenterInterlinks.jl ? Or is it possible to specify custom links for some methods from other packages?

---

<div class="post-metadata">

**Author:** ![dcelisgarza](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dcelisgarza/32/215951_2.png) [@dcelisgarza](https://discourse.julialang.org/u/dcelisgarza)\
**Post date:** [August 7, 2026, 6:55pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/7 "2026-08-07T18:55:13Z")

</div>

I’m trying it whilst using DocumenterVitepress.jl but it doesn’t seem supported :(. Would it be a matter for DocumenterVitepress.jl or DocumenterCodeBlocks.jl?

---

<div class="post-metadata">

**Author:** ![lazarusA](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lazarusa/32/6571_2.png) [@lazarusA](https://discourse.julialang.org/u/lazarusA)\
**Post date:** [August 8, 2026, 6:52am UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/8 "2026-08-08T06:52:40Z")

</div>

probably DocumenterVitepress 😃 , and possible and small caller extension will be needed. Open to PRs 👍

And oh!! nice we have this in Julia now, I always wanted to have something similar to `twoslash` [Syntax Highlighting with Twoslash | Twoslash](https://twoslash.netlify.app/guide/highlight), now is here ❣

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [August 8, 2026, 9:15pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/9 "2026-08-08T21:15:06Z")

</div>

It is probably neither. DocumenterCodeBlocks modifies the generated HTML and that probably looks completely different in the Vitepress output.

---

<div class="post-metadata">

**Author:** ![odow](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/odow/32/28685_2.png) [@odow](https://discourse.julialang.org/u/odow)\
**Post date:** [August 10, 2026, 2:56am UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/10 "2026-08-10T02:56:03Z")

</div>

This is fantastic!!! I’m going to add it to the JuMP documentation, which should give it a very good thrashing: [[docs] add DocumenterCodeBlocks.jl - Pull Request #4216 - jump-dev/JuMP.jl - GitHub](https://github.com/jump-dev/JuMP.jl/pull/4216)

I have a couple of questions, but I’ll open an issue for them.

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [August 12, 2026, 8:21am UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/11 "2026-08-12T08:21:34Z")

</div>

Thanks for trying it out and for giving feedback. Version 1.2.0 is released now see [DocumenterCodeBlocks.jl/CHANGELOG.md at main · fredrikekre/DocumenterCodeBlocks.jl · GitHub](https://github.com/fredrikekre/DocumenterCodeBlocks.jl/blob/main/CHANGELOG.md#v120---2026-08-12).

---

<div class="post-metadata">

**Author:** ![odow](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/odow/32/28685_2.png) [@odow](https://discourse.julialang.org/u/odow)\
**Post date:** [August 12, 2026, 7:08pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/12 "2026-08-12T19:08:10Z")

</div>

Here are the JuMP docs using it: [Introduction · JuMP](https://jump.dev/JuMP.jl/dev/)

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [August 13, 2026, 2:11pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/13 "2026-08-13T14:11:21Z")

</div>

After talking to @giordano, version 1.3.0 support continuing the numbering between code blocks and also the option to let numbering to follow Documenter block names (this should probably have been the default but oh well). You can either configure this inline in Markdown with the new

````julia-auto
```@codeblocks
line_counter = ...
```

````

configuration block (similar to Documenters `@meta` blocks).

See [DocumenterCodeBlocks.jl/CHANGELOG.md at main · fredrikekre/DocumenterCodeBlocks.jl · GitHub](https://github.com/fredrikekre/DocumenterCodeBlocks.jl/blob/main/CHANGELOG.md#v130---2026-08-13).

---

<div class="post-metadata">

**Author:** ![franckgaga](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/franckgaga/32/218241_2.png) [@franckgaga](https://discourse.julialang.org/u/franckgaga)\
**Post date:** [August 14, 2026, 4:19am UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/14 "2026-08-14T04:19:31Z")

</div>

Marvelous! Now I wanna do the same for the documentation of ModelPredictiveControl.jl ! ✨

🏆 **NEW SIDEQUEST ACQUIRED**

---

<div class="post-metadata">

**Author:** ![dcelisgarza](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dcelisgarza/32/215951_2.png) [@dcelisgarza](https://discourse.julialang.org/u/dcelisgarza)\
**Post date:** [August 14, 2026, 9:22am UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/15 "2026-08-14T09:22:17Z")

</div>

This is making me want to use Documenter.jl over DocumenterVitepress.jl

---

<div class="post-metadata">

**Author:** ![scheidan1](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/scheidan1/32/24771_2.png) [@scheidan1](https://discourse.julialang.org/u/scheidan1)\
**Post date:** [August 14, 2026, 12:34pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/16 "2026-08-14T12:34:25Z")

</div>

That look great and could be very helpful!

I was wondering if an option to flip the normal order of the docstring would be useful: showing how to call a function is not the first thing I want to know when I already hover my mouse over a function call. I’d rather want to learn what it does.

---

<div class="post-metadata">

**Author:** ![csvance](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/csvance/32/218927_2.png) [@csvance](https://discourse.julialang.org/u/csvance)\
**Post date:** [August 14, 2026, 1:19pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/17 "2026-08-14T13:19:37Z")

</div>

> [@dcelisgarza](#):
>
> This is making me want to use [Documenter.jl](https://juliaregistries.github.io/General/packages/redirect_to_repo/Documenter) over [DocumenterVitepress.jl](https://juliaregistries.github.io/General/packages/redirect_to_repo/DocumenterVitepress)

I have never been so conflicted in my entire life 😅 I wonder how difficult it would be to get the Vitepress style landing page with the tiles in base Documenter.jl. Guess its time to find out 😎

---

<div class="post-metadata">

**Author:** ![dcelisgarza](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dcelisgarza/32/215951_2.png) [@dcelisgarza](https://discourse.julialang.org/u/dcelisgarza)\
**Post date:** [August 14, 2026, 3:01pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/18 "2026-08-14T15:01:48Z")

</div>

Don’t you pull a “we have legos at home” only to show me some crusty-ass 1970s, lead-painted megablocks, bro.

---

<div class="post-metadata">

**Author:** ![csvance](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/csvance/32/218927_2.png) [@csvance](https://discourse.julialang.org/u/csvance)\
**Post date:** [August 14, 2026, 3:30pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/19 "2026-08-14T15:30:04Z")

</div>

> [@dcelisgarza](#):
>
> Don’t you pull a “we have legos at home” only to show me some crusty-ass 1970s, lead-painted megablocks, bro.

🤣

Now you can have your crusty-ass 1970s, lead-painted megablocks and eat them too!

[https://csvance.github.io/DocumenterLandingPage.jl/dev/](https://csvance.github.io/DocumenterLandingPage.jl/dev/)

---

<div class="post-metadata">

**Author:** ![dcelisgarza](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dcelisgarza/32/215951_2.png) [@dcelisgarza](https://discourse.julialang.org/u/dcelisgarza)\
**Post date:** [August 14, 2026, 3:39pm UTC](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552/20 "2026-08-14T15:39:57Z")

</div>

Now i _really really_ have to think about switching back.

[Next page](https://discourse.julialang.org/t/documentercodeblocks-jl-announcement/138552.md?page=2)