Fix bin/gen_diagrams that is referenced in docs

[jeff-hykin]

Closes DIM-553

[greptile-apps]

Greptile Summary

This PR adds the missing bin/gen-diagrams script that was referenced in the docs but didn't exist, and fixes the docs reference from the old underscore name (gen_diagrams) to the hyphenated name (gen-diagrams). The script wraps md-babel-py to process diagram code blocks (pikchr, asymptote, openscad, diagon) in markdown files, with a nix-based fallback if md-babel-py isn't installed locally. The docs update also adds mermaid as a supported diagram language.

• Adds bin/gen-diagrams bash script with dependency detection, nix fallback, and support for both explicit file arguments and automatic docs/ scanning
• Fixes broken bin/gen_diagrams reference in docs/development/writing_docs.md to match the new hyphenated filename
• Minor typo in docs: "diagrams languages" should be "diagram languages"

Confidence Score: 4/5

• This PR is safe to merge — it adds a straightforward utility script and fixes a broken docs reference.
• The changes are small, well-scoped, and low-risk. The script follows good bash practices (set -euo pipefail, proper quoting), provides helpful error messages, and the docs fix is a clear correction. Only a minor typo in the docs prevents a perfect score.
• No files require special attention.

Important Files Changed

Filename	Overview
bin/gen-diagrams	New bash script that wraps md-babel-py for diagram generation with a nix fallback, supporting both explicit file arguments and automatic discovery of all docs/*.md files.
docs/development/writing_docs.md	Fixes the script reference from bin/gen_diagrams (underscore) to bin/gen-diagrams (hyphen) and adds mermaid as a supported diagram language. Minor typo: "diagrams languages" should be "diagram languages".

Flowchart

flowchart TD
    A["bin/gen-diagrams invoked"] --> B{"Arguments provided?"}
    B -- Yes --> C["Iterate over provided files"]
    B -- No --> D["find ./docs -name '*.md'"]
    D --> E["Iterate over found files"]
    C --> F{"md-babel-py installed?"}
    E --> F
    F -- Yes --> G["Run md-babel-py run FILE --lang langs"]
    F -- No --> H{"nix installed?"}
    H -- Yes --> I["Define md-babel-py wrapper via nix run"]
    I --> G
    H -- No --> J["Error: install nix or md-babel-py"]

Loading

_{Last reviewed commit: 1056faa}

[greptile-apps]

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[spomichter]

@leshy this is your stuff is this fine

[leshy]

All this does is executes md-babel-py run - this is just another adapter layer to maintain and should be a personal shell alias not a /bin/ script imo.

if others need this, that's ok and can add it - but expectation is for scripts in /bin/ to always work and be up to date

[jeff-hykin]

~30 lines is not an alias; even ignoring the installation help/check, at the bottom there's a for loop for iterating over all the file paths -- a for loop doesn't fit in an alias. I have lots of my own aliases for things that are just-for-me. This was designed specifically to help others.

Idk why but md-babel-py seems to only be able to handle one file path at a time, using shell globbing doesn't work. If you add support for that it would make this wrapper less necessary.

expectation is for scripts in /bin/ to always work

Yes? This function should always work. If contributors are not able to generate diagrams for docs in one line thats a problem IMO. Why would we make each person on the team copy this wrapper and define it in their own shell?
If we add a new diagram lang we can just change this function instead of telling everyone else to change their alias's.

[jeff-hykin]

If anything IMO it would be nice to add a --watch flag to this script so that real-time editing of diagrams can be rendered locally instead of needing to run the command every time.

Also I made a PR on md-babel-py to make it work with Nix on MacOS whenever you get the chance to merge it:
leshy/md-babel-py#1

[leshy]

ok I merged your md-babel PR, and published to pypy (v1.1.2) tnx for mac support!

I actually didn't write a single diagram by hand yet (have you?) agents have been drawing those for me, in docs instructions they know how to regenerate, this is why I didn't work on ergonomics of this.

but all above is good and reasonable imo, I'd prefer to add these things to md-babel-py directly, both --watch and --recursive, instead of adding an adapter layer like this. md-babel-py is a mostly quickly vibed project for me to write the docs, so I'd just vibe those commands as well.

As for re-generating diagrams, I'd add an option (temporarily) directly to md-babel-py - --diagrams but actually much better, I wouldn't differentiate code blocks vs diagram blocks and I'd add some caching mechanism (hash in code block args after language) for unchanged code blocks to not be re-evaluated.

I still think above adds a random layer that should be in md-babel-py but won't block since not very important, I let you decide