I use Excalidraw to manage my diagrams for my blog (blog.lysk.tech)

Huge fan of https://github.com/mermaid-js/mermaid, not the prettiest things but enough to scratch the itch.

Cool, I did a similar thing last week.

I made a custom Payload CMS block that allows to create and update excalidraw diagrams within the CMS. It supports dark and light mode switching and rendering inline or as external SVG.

And last weekend I added MCP server with Oauth so I could generate and update those diagrams and add them to post drafts from Claude. I think it is more convenient since I don't have to use API billing model and don't need to build a custom UI.

Here is an example post: https://www.janhouse.lv/blog/network/self-hosting-tailscale-...

Originally I wanted to sync posts from Obsidian but it doesn't have good enough image handling which I sometimes need and I needed extra metadata to unlist or password protect or noindex some posts.

Documentation often rots away because it's often decoupled from the code it describes.

I'm a huge fan of anything related to code that can I check into git, track its evolution and the thinking that went behind it. Why was Kubernetes chosen? Why was NATs chosen? Why are the topics named the way they are?

I am a huge fan of mermaid diagrams because it lets me check in my diagrams into git. I am a huge fan of mermaid diagrams because my code can generate diagrams that I (or they) can check into git - and this was before AI.

Now that AI can generate mermaid diagrams, people look at my Git repos and go "oh, you use AI a lot!" - then I point to my git history and they see it's from 2018.

I'm really happy that mermaid and related tools like Excalidraw are taking off - we have another chance at documentation being automated, uptodate and "fresh".

Looks pretty cool. I think it's great that you support light/dark mode. FWIWI, I'm also a huge fan of Excalidraw.

I wanted to ask you: is there's a reason you use a separate svg file for each (light/dark) mode?

A single SVG file using CSS can change it's own colors based on the user's preference. I have an example here: http://alejo.ch/3jj - the 3 plots should honor your mode (I put the generator code here: https://github.com/alefore/mini_svg)

Just figure I'd ask. If you have a good reason for using separate files, I'd love to hear it (because it probably would also apply to what I'm doing). :)

Same. I started using it for Gethly blog. It's not perfect, some things make me crazy but overall it is better than draw.io that I used to use before. Excalidraw also has these great styles that just feel right :)

Small related problem I am having, wondering if there’s an existing solution for it:

I draw a lot of software diagrams on Mac. Lots of rectangles, arrows, and free text. I’m wondering if there’s anything that clean up my freehand boxes and potentially even text into something a little nicer? I want the boxes to snap to a nicer rectangle, the arrows to look cleaner, and the text to be more legible.

I could send the whole thing into an LLM and maybe that would work, but I also fundamentally feel like that’s overkill and less reliable.

I tried Freeform which apparently has that functionality on iPad, but wouldn’t you know the one thing you cannot do with Freeform on a Mac? Draw free form.

You can also bootstrap your initial schema with LLMs with the excalidraw MCP "app" [0]. But MCP "apps"[1] are quite new and not very well supported yet.

[0] -- https://github.com/excalidraw/excalidraw-mcp

[1] -- https://modelcontextprotocol.io/extensions/apps/overview

I love diagramming, but I genuinely don't understand how people can use these wonky looking tools. It looks off, I had to make my own[1] to create something that's easy to use and looks good/normal.

[1] https://grafly.io

I want to love Excalidraw but it can be really frustratingly mediocre a lot of the time. For example, I'm constantly retrying to rescale something and then an arrow repositions or resizes itself, which reveals some kind of mistake in the underlying data model. Or undo/redo just doesn't work correctly. Or you're draw an arrow and try as you might it refuses to not attach itself to some other element. And all sorts of things that should be customizable are not (like defaulting to the non-rough style, or resizing arrows separately from line thicknesses). And there is a basically-complete pull request for a math mode (https://github.com/excalidraw/excalidraw/pull/6037) which has been in limbo for years. Probably there are other things I'm forgetting.

Anyway, it's kind of annoying to use for reasons like these. Just thought I would mention it since all the comments here seem positive.

It would have been great if Excalidraw made it easier to do manage multiple scenes. I use its PWA and save individual files on the disk.

I have noticed diagrams are most useful early in thinking, but once things get complex they either become outdated or too hard to maintain. Curious how people here deal with that, do you keep diagrams in sync with code, or treat them as disposable?

Wow, I had no idea that excalidraw could "import" mermaid!! This is just awesome.. I can have my LLM generate mermaid, which it is really very good at. And then I can edit the diagram!

I simply just draw in excalidraw and take a ss and past it in my obsidian note, I have a setup that automatically parses posts from my vault and then pushes them to my site

Everyone does that these days and they are becoming AI tells like the em-dash or the blue-glow of the early AI generated images that everyone added to their blog posts.

That fits perfectly with the idea that everything should actually be in the repository. At last, I no longer have to update the images myself. Thanks!

Excalidraw has proliferated quite widely in my company since we got Claude Code. Its a shame the default font is ugly, childish and inaccessible.

Interesting approach. I make heavy use of Mermaid as I find it easier to make small changes and bulk generate-and-copy for publishing elsewhere. But being able to update the diagram and automatically generate the output files is a nice hybrid.

And I'm over here using Graphviz like some caveman.

Obsidian also offers a full excalidraw integration

Great article, should make sure to attribute xkcd comics though.

https://xkcd.com/about/

I want to write a blog whose posts will be all about the technical details of how the blog works.

Should be Show HN.

Now it reads like an ad for some extension to a program I've never heard about.

Love Excalidraw. Used it for decades now, but reach for more powerful tools pretty often as I hit its limits. I'm not asking for the world, but some basics like being able to bold or italicize text would help out a lot.

Another option I use open is to ask the code-agent to make a diagram using Tikz (as a .tex file), which can then be converted to pdf/png.

But in general AI-diagramming is still unsolved; needs several iterations to get rid of wonky/wrong arrows, misplaced boxes, misplaced text etc.

YES YES YES! Excalidraw is amazing, I recently embedded it into my vibe coded project to add version control integration with it. Honestly one of highest quality tools I've used for my workflow, does what it needs to do and doesn't get in your way.

nice one!

Uh, that’s a nice approach.

[dead]