Restructure Diagram

Docs restructuring diagram

Generate a planning diagram that mirrors a docs section's folder/page tree as

two identical columns — before (left) and after (right) — with an arrow

joining each item to its copy. The after column starts as an exact duplicate;

the human then opens the file in diagrams.net and

drags the after boxes into the proposed new structure, the arrows tracking

where each page moved.

This is the tool that drew the NRedisStack client-docs migration diagram and the

RDI redis-data-integration restructure. The output is an *editable* SVG: it

renders as an image anywhere, and opening it in draw.io gives back real boxes

and arrows because the model is embedded in the SVG content attribute.

When to use

• Planning a reorganisation of any folder under content/ (moving pages

between sections, splitting/merging sections, reordering).

• Sharing a "here's the current shape, here's the proposed shape" picture with

reviewers before doing the actual file moves.

How it reads the docs

The generator (build_diagram.py) walks the section folder and builds the tree

automatically. It does not guess — it reads the source:

• Order follows each file's Hugo weight frontmatter (ties broken

alphabetically by label), matching the live left-hand nav.

• Box text is the linkTitle frontmatter (falls back to title, then the

filename) — generally more compact than the full title.

• Folders/sections (anything with an _index.md) are shaded yellow;

individual pages are white.

• Asset folders with no _index.md (e.g. ones holding only openapi.json

or dashboard JSON) are skipped — they aren't navigable doc sections.

Workflow

• Pick the section root — the folder to diagram, e.g.

content/integrate/redis-data-integration.

• Decide which folders to collapse. Some sections contain many similar

child pages that aren't individually interesting for a restructure (a long

list of CLI commands, per-database setup pages, every release note). Collapse

those: the folder shows as one yellow box with a single indented ...

sub-box, instead of dozens of rows. Pass them via --collapse as paths

relative to the root. Everything not collapsed is expanded in full.

• Run the generator (from the repo root):

   python3 .claude/skills/restructure-diagram/build_diagram.py \
     content/integrate/redis-data-integration \
     --out RDI-docs-restructure.drawio.svg \
     --collapse data-pipelines/prepare-dbs data-pipelines/transform-examples \
                reference/cli reference/data-transformation release-notes

It writes the .drawio.svg, validates that both the SVG and the embedded

model parse, and prints the row count and the tree it produced. Read the

printed tree back to the user to confirm it's what they expected.

zsh gotcha: pass each --collapse path as its own literal token (as

above). zsh does *not* word-split an unquoted variable, so

--collapse $PATHS sends all the paths as one string that matches nothing

and silently collapses nothing (you'll see a much larger row count). If the

row count looks too big, this is the cause.

• Confirm placement. The default output filename is

<section>-restructure.drawio.svg in the current directory. These are

planning artifacts — write them to the repo root (or wherever the user asks),

not into content/, so they aren't published. Mention where you put it.

• Hand off. Tell the user the after column is currently identical and is

theirs to rearrange in draw.io.

Arrow routing (--edge-style)

The arrows join each before box to its after copy. Default is straight.

• straight *(default)* — point-to-point diagonals. Each line has its own

slope, so once after-column boxes are moved the lines cross but never stack.

This is the routing that actually keeps a busy diagram legible.

• curved — draw.io's "Curved" preset (smooth orthogonal S-bends). Looks

softer, but still routes through the shared central channel, so heavily-moved

lines can still overlay. Use for aesthetics, not to fix overlap.

• orthogonal — right-angle rectilinear (draw.io's default). Tidy at rest;

overlays badly after a rearrange.

Note: a true point-to-point *bezier* isn't offered — draw.io only curves edges

that have bends (orthogonal routing) or fixed waypoints, and baked-in waypoints

would break as soon as the user drags a box. straight is the closest thing to

"clean independent lines". The edge style can always be changed afterwards in

draw.io's Format panel.

Cross-branch pages (--add)

The walk only sees the working tree. If a page exists on another branch (e.g. an

in-progress page on a feature branch you're not on) and should appear in the

diagram, inject it manually:

--add "data-pipelines/supported-types.md::Supported data types::80"

Format is REL_PATH::LABEL::WEIGHT (path relative to root). The page is placed

among its siblings in weight order, just as if it were on disk. Repeatable.

Prefer regenerating from the branch that has the page if you can; use --add

only when you can't.

Guardrails

• Check the branch first. The diagram reflects the current working tree.

Note the branch in your summary — a page missing from the diagram is usually a

page that lives on a different branch, not an error. (This is easy to misread

as data loss.)

• Don't hand-edit the XML for structural changes — change the inputs and

rerun, so the diagram stays reproducible.

• The script needs no network and only reads the docs tree; it's safe to run in

the sandbox.

Files

• build_diagram.py — the generator. --help lists all options. Layout

constants (box size, indent, colours, font) are near the top if you need to

tweak the look; the default style matches the existing migration diagrams

(Space Grotesk, yellow #fff2cc sections).