Skip to content

docs: render CairoMakie figures as SVG, like Plots - #933

Merged
ocots merged 1 commit into
mainfrom
docs/cairomakie-svg
Sep 1, 2026
Merged

docs: render CairoMakie figures as SVG, like Plots#933
ocots merged 1 commit into
mainfrom
docs/cairomakie-svg

Conversation

@ocots

@ocots ocots commented Sep 1, 2026

Copy link
Copy Markdown
Member

What

Phase K (#921) added the first Makie page — examples/logo.md — but its three figures render as raster PNG. DocumenterVitepress ranks image/png (4.0) above image/svg+xml (3.0), and CairoMakie — contrary to the note in Handbook/VITEPRESS-DOC.md ("CairoMakie … No action needed") — responds to both MIME types, so PNG wins.

Fixed the same way as Plots (#903): disable PNG capture globally in make.jl.

using Plots
import CairoMakie   # import, not using — see below
Base.showable(::MIME"image/png", ::Plots.Plot) = false
CairoMakie.activate!(; type="svg")
Base.showable(::MIME"image/png", ::CairoMakie.Makie.Figure) = false

Why import, not using: using CairoMakie pulls Makie's plot / plot! into Main, where they collide with Plots' — the @docs block on results/plot.md then fails with undefined binding 'plot!' and terminates the build. import keeps the extension-loading (so Makie.plot(sol) still works on the logo page) without the namespace pollution.

Verification

Full julia --project=. docs/make.jl: exit 0, 0 Cannot resolve @ref, no docs_block error. All 50 built figures are now .svg (the logo page's three included). Only remaining build errors are the 4 unchanged Phase-D @extref items.

Companion

Handbook/VITEPRESS-DOC.md's "Plot image format" bullet still says CairoMakie needs no action — corrected in Handbook#18.

Add the run documentation label to build the site in CI.

🤖 Generated with Claude Code

Phase K added the first Makie page (examples/logo.md) but its figures came
out as raster PNG: DocumenterVitepress ranks image/png (4.0) above
image/svg+xml (3.0), and CairoMakie — contrary to the note in
Handbook/VITEPRESS-DOC.md — responds to both MIME types, so PNG won.

Fixed the same way as Plots (#903): disable PNG capture globally in
make.jl so DocumenterVitepress falls back to SVG.

- `import CairoMakie`, not `using`: `using` would pull Makie's `plot` /
  `plot!` into Main, where they collide with Plots' and break the `@docs`
  block on results/plot.md (`undefined binding 'plot!'`).
- `CairoMakie.activate!(; type="svg")` + `Base.showable(::MIME"image/png",
  ::CairoMakie.Makie.Figure) = false`.

Verified: full build exit 0, 0 unresolved @ref, all 50 built figures are
now .svg (the logo page's three included).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@ocots ocots added the run documentation Trigger the Documentation workflow on this PR label Sep 1, 2026
ocots added a commit to control-toolbox/Handbook that referenced this pull request Sep 1, 2026
Current CairoMakie (0.15) responds to `image/png` just like Plots, so
DocumenterVitepress picks PNG for Makie figures too — the "produces SVG
automatically, no action needed" note was wrong. Give the same global
`Base.showable` fix for both, and the `import CairoMakie` (not `using`)
caveat that avoids a `plot!` collision in `@docs` blocks.

Found while rendering OptimalControl.jl's logo page (control-toolbox/OptimalControl.jl#933).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@ocots
ocots merged commit d8544e7 into main Sep 1, 2026
8 checks passed
@ocots
ocots deleted the docs/cairomakie-svg branch September 1, 2026 07:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

run documentation Trigger the Documentation workflow on this PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant