search

yuzutech / kroki

Creates diagrams from textual descriptions!
https://kroki.io
MIT License
2.78k stars 206 forks source link

Make it easy to embed in github markdown with human readable URL encoding #3

Open baragona opened 5 years ago

ggrossetie commented 5 years ago

What do you think about this format:

GET /<diagram_type>/<output_format>/plain:<source>

A few examples:

When using the /blockdiag, /seqdiag and actdiag or /nwdiag endpoints we could make the enclosing curly braces optional:

But we should address this feature in another issue.

laurilubi commented 4 years ago

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.

UPDATE 2: @Mogztter looked into this and found that http://www.txtwizard.net/compression uses both base64 decode and inflate - which absolutely makes sense.

ggrossetie commented 4 years ago

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.

laurilubi commented 4 years ago

@Mogztter Any possiblity to share it privately? Otherwise I have to check with the team how much to anonymize it.

ggrossetie commented 4 years ago

Sure you can send me an email at: hello at kroki.io 👍

ggrossetie commented 4 years ago

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?

laurilubi commented 4 years ago

It would absolutely solve the issue we started on with - keeping the source of truth in image URL only. @Mogztter

cben commented 4 years ago

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:

ggrossetie commented 4 years ago

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.

ggrossetie commented 4 years ago

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.

ggrossetie commented 2 years ago

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