search

Pluralith / pluralith-cli

A tool for Terraform state visualisation and automated generation of infrastructure documentation
https://www.pluralith.com
Mozilla Public License 2.0
789 stars 51 forks source link

Add image options for export and not just pdf #81

Open Shocktrooper opened 2 years ago

Shocktrooper commented 2 years ago

Unfortunately most markdown implementations do not allow PDFs to be rendered which adds an extra step that end users have to do to render them in their repository markdown files. Alternative graph generation export options are handy to alleviate this manual step and allow for clean embedding of arch diagrams in a repository.

DanThePutzer commented 2 years ago

@Shocktrooper this one has been requested before. The Pluralith dashboard actually allows for PDF and PNG exports and also has dedicated markdown integration support where we always show the latest diagram in your docs, with specific filters you set. (This is, however, a paid feature at the moment).

Having PNG exports in the CLI does make a lot of sense, but there's been one technical thing that kept us from implementing it so far: When you export through the Pluralith dashboard (since we are PDF-first) we actually generate the PDF and then the PNG from that PDF (this is what happens server-side when you export from the UI). This has some third-party dependencies that we didn't really want to ship/require for the CLI (such as imagemagick).

Making this happen locally, without sending anything to the server, is a bit of a mess. We'd either have to require people to install the needed third-party dependencies (which we don't really like, we're trying to make it as self-contained and simple to run as possible) or reimplement the diagram drawing that we currently do for the vector-based PDF for pixel-based PNGs (which is quite a bit of work).

What's your opinion on this?

Shocktrooper commented 2 years ago

Mmmmm I would err on the side of generating a vector based image if possible mostly because if someone tries to zoom in on an image we would want to keep the quality no matter how zoomed in. A pixel based image would have to be incredibly dense/large to get the same zoom quality level. To alleviate 3rd party dependencies packaged with the initial cli you could probably follow the module based approach that you do with the graph module itself. That way it doesn't bloat the initial install and is available if someone wants to use it down the line with an additional installation.

DanThePutzer commented 2 years ago

Is there a popular vector-based image format that's widely readable? When I think "image" I always think about PNG pr JPG haha, any specific format you'd suggest?

Regarding the modular approach: Something like that would work, I'll tinker a bit on how to best handle installation across various OS and will report back!

Shocktrooper commented 2 years ago

When I think vector I think SVG but looking into markdown implementations like the popular Kramdown it appears that the image support is actually on the side of who is implementing the library and not the markdown library itself. The 2 most popular Git tools both support SVG it seems as well so I would go with that if possible. I am also willing to bet that whichever library you use for image exportation probably supports a myriad of image options and not just 1.

References:

DanThePutzer commented 2 years ago

Ah of course SVG, we actually use that under the hood for the diagram itself and then embed it into the PDF. I guess my brain doesn't see SVG as an image format, but I guess it actually is one haha (When I think "image" I think "can I view it on my phone?")

It should be rather straight-forward to generate an SVG export of the diagram even without the third-party library, given that we already have the diagram itself as SVG. We'd want to put the usual frame around it with diagram title, branch, version etc. so we'll have to make that part of the SVG as well (currently that is part of the native PDF generation). Shouldn't be too difficult, but it's a bit of work (those PDF and SVG libraries are a bit of a mess to work with).

I've added it to our backlog and will get to it asap! We've got a few important things we're working on right now with some deadlines (#52, #44, #78 and the Azure DevOps integration), but maybe I can slip this in between tasks in the next few weeks 👍