yuzutech
Make it easy to embed in github markdown with human readable URL encoding
What do you think about this format:
GET /<diagram_type>/<output_format>/plain:<source>
A few examples:
/blockdiag/svg/plain:blockdiag%7B"Kroki"->"generates"->"Block%20diagrams"%7D/graphviz/svg/plain:digraph%7BHello->world%7D/plantuml/svg/plain:Bob->Alice:hello
When using the /blockdiag, /seqdiag and actdiag or /nwdiag endpoints we could make the enclosing curly braces optional:
/blockdiag/svg/plain:"Kroki"->"generates"->"Block%20diagrams"
But we should address this feature in another issue.
That would help us to store source of a diagram in only one place. But it seems like the PR has not been accepted into master branch. Any plans to support plain:? Alternatively support decode so that the diagram source can be recovered from the image url.
UPDATE: I got this working when decoding the source with inflate only, not a combination of inflate and base64 as docs suggest on kroki.io.
- http://www.txtwizard.net/compression - choose deflate, decompress, works
- https://www.samltool.com/decode.php - does not work
UPDATE 2: @Mogztter looked into this and found that http://www.txtwizard.net/compression uses both base64 decode and inflate - which absolutely makes sense.
That would help us to store source of a diagram in only one place. But it seems like the PR has not been accepted into master branch. Any plans to support plain:?
I'm still not sure if we should support this feature or not.
Alternatively support decode so that the diagram source can be recovered from the image url.
I need to give it some thought.
I got this working when decoding the source with inflate only, not a combination of inflate and base64 as docs suggest on kroki.io.
Could you please share your diagram ? I can confirm that we are using deflate + base64 so I don't really know you got it working.
@Mogztter Any possiblity to share it privately? Otherwise I have to check with the team how much to anonymize it.
We might want to add the decode/encode feature in the Kroki CLI (similar to what PlantUML is doing). I think it makes more sense than adding this feature to the Kroki API.
Something like:
$ kroki encode hello.dot
eNpLyUwvSizIUHBXqOZSUPBIzcnJ17ULzy_KSeGqBQCEzQka
$ kroki decode eNpLyUwvSizIUHBXqOZSUPBIzcnJ17ULzy_KSeGqBQCEzQka
digraph G {
Hello->World
}
@laurilubi What do you think?
It would absolutely solve the issue we started on with - keeping the source of truth in image URL only. @Mogztter
Gravizo has a clever "Indirect" mode where the URL points back to a file containing the diagram source. If you don't want a separate file, they also allow specifying a delimiter for finding a section of the file, so you can keep the diagram source nearby in the README itself. See https://github.com/TLmaK0/gravizo, https://bitbucket.org/TLmaK0/gravizo-example/ for examples of both.
[P.S. http://www.gravizo.com still documents directly using a multi-line image URL, which was a brilliant find but no longer allowed in GitHub CommonMark — https://github.com/TLmaK0/gravizo/issues/29. The indirect mode was their next-best workaround :wink:]
The benefit is having readable editable source (rather than ugly encoding) in README :sparkles:
Main drawbacks are:
- URL has to point to repo, which breaks on forks. :fork_and_knife: (Once upon a time I hoped image rendering services could use Referer header to find the repo/fork automagically, but nowdays with GitHub's "camo" image proxy that can't work.)
- URL stops being lone "source of truth" :arrow_upper_right:. As a user, I'd happily give that up rather than opaque encoding. As API authors, you might disagree ;-)
- This causes caching issues, as diagram may change but keep same URL 🏚️... cf. https://github.com/TLmaK0/gravizo/issues/39
The public instance of Kroki does not do any remote call for performance/security reasons so this approach won't work 😐
I purposely want to keep the API as simple as possible. It takes a text diagram as input and returns an image.
The benefit is having readable editable source (rather than ugly encoding) in README ✨
I agree that's is not ideal but the alternative solutions are really just workarounds. If you are using AsciiDoc, I would recommend to use Asciidoctor Kroki 😉 You can write the following:
Let's take an example with a _GraphViz_ "Hello World":
[graphviz]
....
digraph G {
Hello->World
}
....
Though it won't work on GitHub/GitLab.
I guess someone could work on a proxy to fetch text diagrams from remote URLs and use Kroki as a backend to convert them to images. It could even be an additional services but I don't want to include it in core.
https://g.kroki.io/plantuml/svg?url=https://raw.githubusercontent.com/yuzutech/kroki/master/hello.puml
With AsciiDoc, you could add an id on your block:
Let's take an example with a _GraphViz_ "Hello World":
[graphviz#hello-world-puml]
....
digraph G {
Hello->World
}
....
https://g.kroki.io/plantuml/svg?url=https://raw.githubusercontent.com/yuzutech/kroki/master/README.adoc#hello-world-puml
The main benefit is that you don't need to pollute your README with details/summary blocks. And if you are viewing the README outside of GitLab/GitHub and you have the Asciidoctor Kroki extensions enabled, it will also work.
What do you think?
For reference, the initial idea was to use: GET /<diagram_type>/<output_format>/plain:<source>.
While it was fitting nicely in the API it would only work on really basic/simple diagrams so I don't think it's worth pursuing this idea.
With AsciiDoc, you could add an id on your block: The main benefit is that you don't need to pollute your README with details/summary blocks.
Actually that's not true because it won't replace the block with the image on GitHub/GitLab :disappointed: I guess that's why the diagram source is "hidden" in the details block but I don't like this solution because the publishing platform is dictating how your content should be written. In other words, it does not make much sense to put the source diagram in a details block when the platform can replace the block with the corresponding image.
Though it won't work on GitHub/GitLab.
Please note that GitLab now has Kroki support: https://docs.gitlab.com/ee/administration/integration/kroki.html