Generate Flowcharts from Text

[lifeisstillgood]

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.

[yubrshen]

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.

[everybodyknows]

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”.

[orthoxerox]

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.

[vjeux]

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.

[codeulike]

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...

[aembleton]

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

[slaymaker1907]

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.

[mumblemumble]

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.

[arbie]

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

[detaro]

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/

[lifeisstillgood]

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.

[statstutor]

Is this not exactly what you want?

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

[joshspankit]

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.

[safanycom]

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

[plainoldcheese]

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

[smusamashah]

A list I compiled of 40+ similar text to diagram tools. https://xosh.org/text-to-diagram/

Input in this one is very simple and cool.

[Veuxdo]

Missing Ilograph: https://app.ilograph.com/

It's heavier-duty compared to most of the others you have listed, but should appeal to engineers who want something more robust.

[kenny87]

Meh, one more: https://structurizr.com/

[ciceryadam]

One more to add: https://diagrams.mingrammer.com/

[mysterydip]

Is there a way to tell which are downloadable/usable offline/locally vs which are websites without clicking through each one?

[breck]

I have some feedback. Would love to chat. My email is in profile.

[taylodl]

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!

[naebother]

And if you're using Sphinx to document, you can also just inline the diagrams in your .rst docs: https://github.com/mgaitan/sphinxcontrib-mermaid

[awaythro15234]

There is also Pikchr, made by Richard Hipp (creator of SQLite).

https://pikchr.org/home/doc/trunk/homepage.md

[Zhyl]

I have now used this to explain some of our architecture to a client over Teams.

If you guys haven't tried building up a diagram, live, step by step like an ad-hoc slideshow, I seriously recommend it.

[xipho]

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.

[monkeydust]

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.

[augusto-moura]

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

[1]: https://plantuml.com/

[pionar]

I've had no problems with PlantUML's compilation time. How large are these documents?

[layer8]

I’m surprised the line-number references don’t auto-adjust when inserting/splitting/joining lines. That’s not very practical.

[tonerow]

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!

[sixti60]

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.

[voxic11]

Another similar tool that I have used in the past is https://mermaid-js.github.io/mermaid/#/

[enlightens]

I've been using that lately for project documentation. The reduction of context-switching has been incredibly helpful.

https://www.luminoslabs.com/insights/text-based-charts-with-...

[flying_sheep]

Did you find a better one? :p Or just no longer making diagrams?

[webdevatlurk]

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.

[tonerow]

Thank you, that's a good suggestion. Making a note

[zupreme]

Every so often a utility feels so intuitive that one thinks, "They finally got it right".

Present feeling: They finally got it right. This is how flowcharts should be made, by default.

[msci100]

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.

[bleepbaboop]

Implementing the use of a '?' in order to generate a diamond shaped "if/else" would be nice. For example:

Some text(2) Yes: (line num) No: (line num)

[flanbiscuit]

This would be nice.

You can do it now with full nodes but would be nice to have a specific node type for that

  This is my chart
   This is a conditional statement
    Yes: Do thing A
    No: Do thing B

[prosaic-hacker]

Box line Text sort of does what I want. https://github.com/jncraton/box-line-text

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.

[jazzex]

I like excalidraw. https://excalidraw.com/

Exports to json or image.

[tijuco2]

I'd like to suggest this one here too https://asciiflow.com/. I've been using it to share ideas with engineers and everybody likes it

[kleer001]

Gorgeous!

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.

[oneweekwonder]

definitely cool for being a spa!

Alternatives is blockdiag[0] with a online demo[1], and then of course graphviz[2] shipped with most distro(s).

[0]: http://blockdiag.com

[1]: http://blockdiag.com/en/blockdiag/demo.html

[2]: https://graphviz.org

[rckrd]

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

[jsmcgd]

It would be great to have an option to be able to save the text to a file, and load text from a file.

Also an ability to click a line and create a connected node.

Also it would be great to drive the app from the diagram, ie generate text from the diagram.

Anyway I like it. I've used Linux Mint's built in Web Apps tool to create an offline version.

[yardshop]

The text lines are just a single textarea element, you can copy from and paste into it. But saving and loading files would be convenient too.