I have come to the conclusion there are two kinds of audience and two kinds of diagram, abs they almost exactly overlap
1. Engineering diagrams, explaining concepts to other engineers who are using the diagram as a jumping off point to deeper explorations
2. "Business" diagrams - the sort of thing we want to see in a Medium article or presentation. The style and correct placement matters far more than engineering.
The first is very amenable to markdown style production - often we want to spend no more than a few minutes creating the diagram. We get (60?) 80% of the way there with 20% effort.
But with every markdown approach I have tried the remaining 20% is flat out days of work. There is almost always a need to place that box there and have this one below and to the right and dammit the layout engine will not agree.
What I would ideally like is a combo - markdown to get me most of the way there, and then drop into some vector format that lets me tweak.
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.
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”.
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.
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.
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.
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.
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.
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/
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
It's much more sophisticated! It might be very powerful to have some wordsmith support in the authoring of the text, for example, in the org-mode of emacs, especially, the collapse (folding) of sub-trees.
I use Mermaid (https://mermaid-js.github.io/mermaid/#/). The killer feature for me - you can write Mermaid scripts in your code comments and there's a plugin available for VS Code that will render it. It's awesome!
I'm in love. I want this as part of an assertion workflow for some of the graph building interfaces we're envisioning for biological data. For example you could allow lines to call from autocompletes, and store some metadata (e.g. extensions of labels) so that the whole widget could be embedded in your tool.
A lot of my emails are becoming like this - structured, bullet points, 'if-then-else' like statement although not that explicit. This could be a nice way to add visualisation to it. Maybe - although everytime I have tried to do something too different with email it has failed.
I would love to see this as a cli, I'm tired of PlantUML's[1] document compilation time. Guess even the plain text tools are made in React nowadays, sigh
Pretty small actually, they don't take like hours, but just a few seconds, the problem is the preview feedback, I like to keep a entr and feh open while a edit the document to give a live preview of my changes, the problem is that the 3-4 seconds latency really mess this up
Are you thinking of the default java gui for previewing plantuml docs? I think there's a timer down there to avoid polling the FS too often. Using a simple editor where everystroke recompiles, red warning in status bar while syntax is not OK (while still displaying the last good one), a 100loc canvas display window, done.
I totally had this thought too when making it. The logic is super simple as-is, so I was scared if I went down the rabbit whole of trying to auto increment/decrement line numbers I might muddy things up. I'll see if add that functionality cleanly at some point (or if you'd like to feel free to take out a PR!) Thanks for the feedback!
alternatively you could link to nodes by referencing their label? You might just also want an option to not render that label (ie have it be for the writer's benefit only).
Nice - that's a great feature. I'm working on a graph based project and have to semi regularly visualise different kinds of directed graph and your project could really come in handy!
I disagree. The simplicity here is a cool and rare feature.
This tool is amazing, and its coolness comes from the fact it's really simple. If you add "auto-adjusting" features that rewrite the code for you while writing, you're on the road to lose the simplicity and KISS aspect.
Please don't add new features, it's like gold as it is, @tone_row. The beauty and magic resides in the minimalism.
This seems really nice as a sketchpad for small flowcharts. I'd definitely use it to map out a small piece of work, because I'm terrible at laying out flowcharts on scrap paper without wasting space or painting myself into a corner.
One minor annoyance: I can't use tab/shift+tab to indent or dedent lines.
This is really cool. I frequently have to build reference architectures for work. I would love to add a feature where if you put quotes around a word, it would search for a folder of logos and add the tool's logo to the square.
For example, typing "Redshift" adds a Redshift db icon to the box.
The blank or edit file can be saved locally as URL or .HTM
file and can be reloaded and continue to be edited.
The UI is missing help, its only on the github page.
Since its just a html file I embedded the help in a comment
in the page. I just view source to look it up. It only adds a few hundred byte to each file.
Some functions don't work for me.
When I get a round tuit I will will try to figure out how it works.
In spite of this it is enough to create impromptu drawings to support a lecture. I save them and give it to the students as part of the notes.
I bet there's a lost history (or oral history, but they're the nearly same after 60+ years) of tools exactly like this that goes back to the times of the PDP-1 and super early hacker culture.
And I bet there's been a version of it written for every operating system at some point. It just seems so necessary and relatively straight forward.
I love when underlying data structures boil down to directed graphs. Turns out that indentation is a bad way to represent graphs (as someone who has tried many times to encode large Kubernetes service topologies in YAML). A language like dot or virgo (https://github.com/r2d4/virgo) seem more appropriate for this task
Unfortunately my corporate firewall/IT-Policy blocks this page, possibly due to the *.fun domain. Any other way to try this out for those working in an office? ( I know I'm an outlier at this time)
setup a web-based proxy in the cloud - make sure its in front of a .com domain (that does not have the word "proxy" in it) and get your SSL certs right.
Here's a popular package: https://mitmproxy.org/ You might have to add some basic auth layer to it so as not to make it open to the world.
It would be great to have this as a command line tool.
I can envision a lot of cool features for this, like being able to add color via text markup, or being able to use circles instead of boxes for the nodes.
Just today I was browsing around for a while for something like this.
But I just can't stand using a website for it, defeats half the purpose of it. I want to be able to commit it to version control and regenerate it on the fly if needed.
In the end I settled with latex+tikz. And was promptly reminded of how clunky it can be, an unnecessary time-sink for a quick sketch (but cool if you need something polished).
I agree, this could really be improved. I'm going to make a github issue so I remember to see if there's a solution to this in the coming days. Thanks for the feedback!
I took a look at the demo of the graphing library that is used and it seems there are some performance issues. Does anyone know how these might be fixed?
I love it. One thing that would be nice is lines and boxes that look like they are hand-drawn. Like Excalidraw. And maybe comic sans font. Or a way to enable that. Because that would be more fun in a brainstorming session.
This is really simple but edge from 6 to 1 should not cross node 4 in the visualization. Also it would be useful to show how to escape or if escaping works at all: how to escape ":" or "(1)"? multiline?
Very interesting. It might be very powerful to somehow integrate with emacs/vim so that their wordsmith capability can facilitate the little discipline in text editing.
Love this interface, slight deviation but related question:
If I wanted to hire a web developer to build a web app that let the user quickly build marketing funnels, what type of person would I be looking for? Front end JavaScript developer?
1. Engineering diagrams, explaining concepts to other engineers who are using the diagram as a jumping off point to deeper explorations
2. "Business" diagrams - the sort of thing we want to see in a Medium article or presentation. The style and correct placement matters far more than engineering.
The first is very amenable to markdown style production - often we want to spend no more than a few minutes creating the diagram. We get (60?) 80% of the way there with 20% effort.
But with every markdown approach I have tried the remaining 20% is flat out days of work. There is almost always a need to place that box there and have this one below and to the right and dammit the layout engine will not agree.
What I would ideally like is a combo - markdown to get me most of the way there, and then drop into some vector format that lets me tweak.