Julia Community 🟣

Michael Anderson
Michael Anderson

Posted on

Keeping doc illustrations consistent with a forty-line Julia prompt matrix

Every docs site accumulates illustrations the same way. Someone needs a figure for the quickstart, someone else needs a cover for a tutorial series, and six months later nothing matches: different stroke weights, different background colours, one image with baked-in text that says the wrong thing. The pictures were made one at a time, by hand, whenever somebody was in a hurry.

The fix I've settled on is small: treat illustration prompts as data instead of prose typed into a box. Keep the brief in a table in your repo, generate the prompt grid from that table, then catalogue whatever comes back by filename. The whole thing is about forty lines of standard-library Julia, which means it survives the next machine you move to.

The unit is a triple, not a sentence

What actually varies between two illustrations on the same docs site is rarely the wording of the prompt. It's three things: which page the image belongs to, what the image is supposed to depict, and what shape it needs to be. That is a table, and tables belong in version control.

const PAGES = ["quickstart", "broadcasting", "plotting"]

const SCENES = [
    "flat vector diagram of a data pipeline, white background, no text",
    "three-panel storyboard of a REPL session, bold outlines, muted palette",
    "abstract cover for a numerical computing tutorial, soft gradient",
]

const RATIOS = ["16:9", "1:1"]

function prompt_grid(pages, scenes, ratios)
    rows = NamedTuple[]
    for page in pages, scene in scenes, ratio in ratios
        push!(rows, (page = page, scene = scene, ratio = ratio))
    end
    return rows
end
Enter fullscreen mode Exit fullscreen mode

Three pages times three scenes times two ratios is eighteen rows, which is already more discipline than I have at 11pm. The important part is not the printing loop, it's that adding a fourth page is a one-line change to a constant, not a decision about tone made from scratch.

Write the grid out, then look at it once

function write_grid(path, rows)
    open(path, "w") do io
        println(io, "page\tscene\tratio\tfile")
        for r in rows
            println(io, join((r.page, r.scene, r.ratio, ""), "\t"))
        end
    end
    return length(rows)
end
Enter fullscreen mode Exit fullscreen mode

The empty file column is deliberate. It starts blank because nothing has been rendered yet, and it is the slot that makes the second half of the workflow possible: once a draft exists, its filename goes in that row, and the row is now a record of which picture corresponds to which brief. Two months later that column is the only reason you can tell why plotting__07.png exists.

Rendering stays manual, and that's fine

I don't automate the rendering step. I paste each row's prompt into a hosted generator, download the result, and rename it. For one recent batch of doc illustrations I used a browser-based generator called Nano Banana 2 Lite (nanobanana2lite.tools), a third-party site that is not affiliated with Google or DeepMind; it takes a text prompt, optionally alongside object references, and returns drafts you download by hand. It is one renderer among many, and nothing in the Julia code below depends on it. If you already script downloads with Downloads.download, keep the naming convention and the rest of this works unchanged.

The point of keeping this step manual is that generating twelve variants of the same diagram is cheap, and picking the one that doesn't look like a deflated balloon is not. Automating the choice would be automating the only part where judgement is actually required.

The filename is the interface

Everything downstream hangs off one convention: <page>__<index>.<ext>, for example quickstart__03.png. Double underscore, because single underscores show up inside page slugs often enough to be a parsing bug waiting to happen.

function classify(name)
    m = match(r"^(?<page>[a-z0-9\-]+)__(?<n>\d+)\.(?<ext>png|jpe?g|webp)$", name)
    m === nothing && return nothing
    return (page = m[:page], index = parse(Int, m[:n]), ext = lowercase(m[:ext]))
end
Enter fullscreen mode Exit fullscreen mode

match returns nothing for anything that doesn't fit the pattern, so a stray Screenshot 2026-11-16 at 09.41.png sitting in the download folder is skipped instead of silently filed under the wrong page. That single nothing branch has saved me more confusion than any of the clever parts.

Catalogue in one pass

Downloads land in one flat folder, and no amount of good intentions keeps them there. One pass sorts them into per-page subdirectories:

function catalogue!(dir)
    buckets = Dict{String,Vector{String}}()
    for name in readdir(dir)
        meta = classify(name)
        meta === nothing && continue
        push!(get!(buckets, meta.page, String[]), name)
    end
    for (page, files) in sort(collect(buckets); by = first)
        dest = joinpath(dir, page)
        mkpath(dest)
        for f in files
            mv(joinpath(dir, f), joinpath(dest, f); force = true)
        end
    end
    return Dict(k => length(v) for (k, v) in buckets)
end
Enter fullscreen mode Exit fullscreen mode

Two details worth keeping. get! inserts an empty vector on first sight of a page name, which removes the haskey-then-push! dance that's easy to get subtly wrong. And sort(...; by = first) makes the report deterministic, so running the catalogue twice and diffing the output tells you whether anything actually changed.

Returning a count per page rather than the file lists themselves also means you can log the result and read it at a glance: quickstart => 6, broadcasting => 6, plotting => 6 is either right or it isn't.

What it buys you

The immediate win is visual consistency: every illustration on the site was asked for in the same vocabulary, at the ratios the layout expects. The second win is reviewability — the grid is a text file, so a prompt change is a one-line diff in the same pull request as the prose it supports. The third is cheap re-runs: when the plotting page gets rewritten, you regenerate six rows, not the whole set.

The limits are just as real. There is no API here, so a batch is minutes of clicking, not seconds of compute. Generated images still mangle text badly enough that captions belong in the markdown, not in the picture. And a prompt table won't make two different renderers agree; it only makes your own set agree with itself.

That trade — a boring text file, a manual render, and a naming convention strict enough to be machine-checkable — has been worth it. The alternative is another folder of final-final-v3.png, and I've had enough of those.

Top comments (0)