I have a love/hate relationship with diagrams, and diagrams-as-code-things (plantuml, mermaid, etc). As a programmer, I find myself trying to turn everything in to a software project: everything must be version control-able. Same with these diagramming solutions -- except I nearly never know what I want the digram to look like, when I start "writing" it. This means I nearly always end up on something like lucid.app just sketching out the solution, and thinking to myself that I'll turn it in to a beautiful diagram with one of the earlier solutions, later -- that never happens. So now I have a diagram I can link to (yay), but can't version control (boo).
Then, I discovered excalidraw[1]: it lets me sketch like lucid, but isn't nearly as polished or robust: you can throw together simple shapes, draw lines between them, and the lines stick to the shapes, so you can move them around and the lines move too. You can also group things together, and draw freehand, and also include text -- what more do you need?
The cool thing about excalidraw is that you can share your drawings, and export them as SVG files -- yay! I can version them again. You can also self-host it, which is a massive plus in my book.
I've been mostly using the VS Code Excalidraw plugin. Any file with name ending on `.excalidraw.svg` or `.excalidraw.png` is an Excalidraw-editable image of the respective format. This means you can save it alongside your markdown docs and embed them directly, but also edit the exact same file on the IDE.
Big Excalidraw fan and I had no idea you could do that...this might be the version controllable solution I've been looking for. Also have given up trying to get mermaid and other solutions to work well.
Is your concern about committing a binary object that is difficult to diff or not being able to recreate/edit the diagram.
Particularly in the latter cases, most of these tools embed the machine readable diagram inside of the PNG. So you can just open the PNG inside of draw.io or excalidraw (if it was created by that tool) and edit the diagram. This is because the plain text file is embedded.
It’s great that lots of tools are going this way. Notably, if you’re doing image generation with Stable Diffusion or Flux, you can just drag a PNG from ComfyUI into the ComfyUI window and get the same whole workflow. It’s a great learning tool.
As for diffs? Well, that’s hard - even if you were diffing the “source” text files for excalidraw or plantUML, a lot can change that makes it nearly impossible to understand. When all that really happened might’ve been a small styling change and moving a node.
Yeah, the most important part of versioning should be the code used to create the diagram, IMO. The result files, whether SVG or PNG, should be packaged as a "release", if you were to use Github.
Excalidraw seems to boil down the important parts of Miro into an even neater and user friendly package. And it seems really modular and have a really interesting API as well. You can use it as a react component for example.
> you can share your drawings, and export them as SVG files -- yay! I can version them again
Out of curiosity, does anyone know of a drawing tool -- like Excalidraw, Lucid or Draw.io -- that has the option of exporting diagrams to code, i.e. something like PlantUML or Mermaid?
Not a diagram tool, but can be used like one, since it converts Python functions into nodes that you can connect to each other and export the resulting layout as images (PNG, SVG, SVG inside an HTML page) or as plain Python code: https://github.com/IndiePython/nodezator
full disclosure: I'm the creator and maintainer of the tool (but this is no advertising, as I released it to the public domain since day 1)
I’ve finally found a happy middle at work where I version control the markdown based “user manual” and API specs/docs, but the design pages, rich with graphs and diagrams are going to live on the corporate wiki and require that I just learn to be disciplined to keep them up to date.
Surely I can just do that and not everything has to be… I dunno what to call it… that thing where us programmers love to see every human process problem as requiring a technical solution.
I'd end up with something like this if I ever had the time. Instead of a corporate wiki, though, I'd probably use something like sphinx to compile PDF files, and store them on the public workspace.
Do you know how excalidraw compares to draw.io? I've used draw.io in the past, but see excalidraw mentioned quite a bit too. I'm not good enough at using draw.io to be against switching for future projects.
The concepts of internal DSLs and external DSLs is relevant here. The article is an internal, to Python, DSL. It runs in the language the tool is written in. Mermaid is an external DSL. You can’t build a Mermaid renderer in Mermaid. For diagrams I’d rather have an external DSL or a macro system than an internal DSL because it looks cleaner IMO. But it’s nice to have syntax highlighting already working in internal DSLs.
Is this a recent addition? I recall attempting to do this some years ago, failing, and putting the tool out of my mind as a result. Maybe I was doing something wrong.
Yes, panic is a large part of the problem. I think I recall the feeling once, when my dad was teaching me to swim around 4 or 5. I think I tried to stand up, and just sunk, then I tried to pull myself up, and grasped at water. I figure at that point my dad just plucked me out of the water and told me to try again haha
You could probably tweak something like Barrier for the kvm/cursor move, and use XPRA to move the window, sure. No idea how much/little work it'd be but doesn't seem like it should be all that complex.
I'm not who you replied to, but I think git is fundamentally insane. It's sufficiently opinionated about how it should be used that if you violate certain customs, it can decide to delete commits that you explicitly created. Despite that, it's not opinionated enough to avoid having a ton of subtly different (or effectively the same) ways of doing a thing on the cli. And the cli is an absolute mess of footguns and inconsistent flags.
That's interesting. I've been using git every day for about 8 years, I've never found myself in a situation where I couldn't fix something I broke. But maybe that time will come.
The usual reasons people hate git are directly resulting from that them not taking time to learn it. If you do know how to use it, you will find it difficult to lose any commits. I suppose the way "reset" has multiple and very different uses is a thorny issue for noobs. But if you just read up when you don't remember, you'll be very safe.
Also, there's snapdrop[1] that does almost the same thing, for free, without the need to install anything. It'd probably be wiser that snapdrop were a native application; then it's dev would not need to pay to host the client application anywhere.
I say this as a software developer using Emacs daily as my IDE: emacs is not an IDE -- at least not OOTB. It can become a competent IDE, but that isn't what it's built for. Instead, I think of Emacs as an overengineered elisp REPL.
That said, I would love to see the issues you mentioned addressed, and would love to see how the EAF[1] does in the future.
I did not, mostly because the parsers are custom to how I want things displayed. Here is a simplified example for Chase, though:
BEGIN{
FS = ",";
}
{
if(FNR > 1){
date = gensub(/([0-9]{2})\/([0-9]{2})\/([0-9]{4})/, "\\3-\\1-\\2", 1, $1);
print date, $3
print " liabilities:chase"
if($5 != "Payment"){
print " expenses:" $4, " $", $6 \* -1.0
}else{
## This exists because I have an offset in the account
## I use to pay the card with. If the amount in my residual
## account != 0, I know there is something wrong
print " liabilities:chase:residual $", -$6
}
}
}
Suppose this script is called 'parse.awk', you would then run:
awk -f parse.awk myfile.csv
I've been doing this for a couple years now and so far I haven't had file formats change on me. Most of the complexity I have experienced so far is when the regex to parse line-items into the appropriate ledger account is non-trivial. It started off as a way for me to learn awk and double entry bookkeeping and somehow turned into something useful.
