Have you tried PlantUML? It provides means of adjusting the layout. I use it often, most of the time the adjustment is good enough for engineering communication within minutes of adjustment. It could be better if there is more cohesive documentation of its support for the adjustment. I had to search on Google many times to figure out how to add the adjustment. The adjustment consists of directives of placement and direction of links, the length of links, grouping of notes, etc. I feel that it's very promising with more popular support.

I have not seen the layout adjustment features, but I’ve very recently been using pandoc and plantuml for all my design docs at work. I find it to be highly productive, though I still end up uploading the resultant word file to one drive for collaboration and review since that’s what everyone else uses.

Is there a javascript/clientside library which implements the plantuml visualizations? Viz.js is linked on plantuml page but it appears to be archived.

For (1), I am sold on goat. ASCII art to SVG, from the command line:

https://github.com/blampe/goat

Embed diagrams in source code comments; build script greps through and writes out an SVG. A caveat is that to be adequately productive, you need rectangle-oriented editing, such as with Emacs’ “M-x string-rectangle”.

Wow, I didn’t know I was looking for this before you shared it! Thank you so much and huge kudos to the authors, this is a fantastic tool.

I agree. I looked at migrating our technical documentation out of MS Office documents into some diffable format and it were the diagrams that killed the initiative.

Tables are a pain, but most technical docs do not require rowspan and other things that are impossible to maintain in Markdown/reST/Asciidoc.

Diagrams are just a shitshow. PlantUML is the biggest player, and it tries to do the right thing by separating semantics and presentation, but kinda fails when your diagram grows too large.

I wish there was some tool that you could feed three separate human-readable inputs:

- styles, which let you define what your elements look like - semantics, which let you describe your elements and relationships - layout, which lets you manually rearrange the elements on your diagram (and is generated by a WYSIWYG tool)

Pikchr generates nice diagrams, but it's an all-in-one dialect. At least when I am reading well-written PlantUML I can understand the meaning of the diagram without seeing the rendered image.

The tool in the OP is nice, but it doesn't let you describe the layout at all.

Ilograph fulfills 2 out of 3: diagrams are broken up into a model (resources) and perspectives (their relations). The layout is always automatic, though. As a plus, though, this allows them to be interactive and dynamic.

Disclosure: I'm the dev

I would love to see an integration with excalidraw where you write text to seed the diagram and then do the touch ups with something like excalidraw. That would solve I think your workflow.

Please give me a combination between Excalidraw and Graphviz, with stylesheets, and layouts generated via a straightforward Python API, immediately displayable in a Jupyter notebook, with a display widget having hooks to move items around, giving auto-updating a Python property dict.

diagrams.net (formerly draw.io) have an xml format that seems fairly open and they can also read/write a bunch of other formats (see here https://www.diagrams.net/blog/import-formats ) so something that gives you their xml format as a starting point might make sense.

discussion of format: https://stackoverflow.com/questions/59416025/format-of-draw-...

Looks like they have an api too: https://jgraph.github.io/mxgraph/docs/js-api/files/index-txt...

This tool (flowchart.fun) does let you download the SVG. You can then edit it in Inkscape.

Just use SVG plus d3. Only trick is coming up with a pipeline to convert this into a pdf or png so that it is easier to use outside the web.

I only throw in D3 because it does have some features which make SVGs more maintainable and easy to write, but I've written many SVGs by hand over the years and it really isn't nearly as bad as many people think it is. I suspect a lot of people think it is very difficult because they only look at the terrible SVGs generated by GUI tools.

Only trick is the solution to entire problem statement.

restofthefuckingowl.jpg

Could you elaborate on the best way to get started with this specifically? Any articles/tutorials you'd recommend?

I've been meaning to forever but both svgs and d3 are complex enough I'm not sure where to start.

I would recommend starting with plain SVG and then exploring D3 after. It's best to think of D3 as a combination of jQuery and a geometry library.

For starting with SVGs, just look for a simple tutorial like https://www.w3schools.com/graphics/svg_intro.asp to get a simple template, but focus on learning the path element. The path element is both foundational to a lot of custom SVG stuff and isn't too complicated, sort of like the Basic of graphics.

Thanks! Really appreciated.

I've gotten the hang of SVGs, is MBostock's blog still the best place to start with D3?

I'm curious if you could get from an 80% solution to a 90% solution by just adding some markup to say things like, "This node should be to the left of this other one?"

Often I use invisible subgraphs to accomplish this sort of thing in GraphViz, but the markup for doing so is complicated and non-obvious.

PlantUML provides such extra "perusation" to the layout. It works often.

But PlantUML's documentation is too scattered that it's hard to know how much it supports.

Overall, to me, PlantUML is one of the more promising trade-off for userability and sophistication.

I wonder if we could pool our resource together to help one reach to more userability.

Input text in https://www.bpmn-sketch-miner.ai/doc/00-intro.html to create a BPMN, download it and edit in Camunda Modeler?

I recently stumbled over a project which tries to do such an approach for graphs in scientific papers, to avoid people manually editing them and them getting disconnected from data sources. They do it by offering export of modified code generating the tweaked variant: https://pylustrator.readthedocs.io/en/latest/

Just a thought / realisation.

"A picture paints a thousand words", so why should we expect it possible to describe some pictures with less words.

Some paintings can be described effectively with "four tins of campbells tomato soup, one in each quadrant".

Other pictures cannot - "Adam reaching out to touch Gods finger"

Maybe we just need to paint sometimes, and maybe learn the difference between the two kinds - when we need to escape from code.

Is this not exactly what you want?

You can write the markdown and then drag and drop boxes (or directly edit the SVG).

This kind of thing is exactly why we need to normalize complex examples.

Have the simple ones front and centre, but also go full pedal to the medal and show flesh out the really complex ones.

Recent and related shout-out: Neo4J has thankfully included some on their API documentation.

Minder is quick, flexible and exports to Mermaid and PlantUML https://github.com/phase1geo/Minder

agreed it would be nice if the markdown just generated a standard svg that you could then edit, or even just an html canvas where you can drag them around a bit more and add some color before exporting as an image

That is exactly what this link does, minus the color.