Allow kroki.io to be disabled in plugin options

[ahus1]

The newly integrated kroki.io service (see #288) sends diagrams in my asciidoc documents to a service in the cloud.

I don't want to share diagrams diagrams with a service in the cloud, and customers I work for usually don't want this as well.

I'd like to see an option to disable kroki.io, ideally have it disabled by default unless the user consents with sending her/his diagrams to a service in the cloud.

[ggrossetie]

It's not documented but you can configure the URL of the server using the attribute kroki-server-url.

For now, one way to disable this feature is to configure the server URL to local/non-existing server.

Please note that you can install a local instance Kroki if you don't want to send your diagram to a cloud service.

And since the Kroki API is compatible with the PlantUML server, you could even configure and use a PlantUML server instead: http://www.plantuml.com/ (but in this case only PlantUML diagrams will be converted to images).

Anyway it's definitely a good idea to provide an option to enable/disable this feature.

[sturtison]

The ability to have diagrams to be created from text is one of the fundamental reasons for the great success of the asciidoctor format and thanks for making kroki.io is another great addition.

Privacy and information security is a consideration and our tools should not be "leaky" by default.

I concur with the idea to enable/disable the feature, with disabled being the "do nothing" disabled default option.

[ggrossetie]

What do you think about this new section in the options page:

Is it clear enough ?

[ahus1]

Thank you for providing these configuration options explicitly!

I've read the texts several times. I'd like it to be more explicit that it sends the text diagrams to the Kroki instance. "using" sounds quite vague to me.

I list some text alternatives below; please feel free to use them, rewrite them or use none of them at all.

The first paragraph is now more explicit. The "convert ... to images" is now "display them as images in the preview" as this is what the user sees. In the second paragraph I added that https://kroki.io is a public cloud service.

The diagrams extension is sending the text diagrams to kroki.io, a free and open-source service, to display them as images in the preview.

By default the diagram extensions sends your diagrams to the free public cloud instance https://kroki.io but you can install Kroki on your own infrastructure.

Reading it again, I think the first checkbox is talking about the software "Kroki", the second one about the instance/installation. Therefore I exchanged kroki.io with Kroki and rewrote the first paragraph. The second paragraph stays the same:

The diagrams extension is sending the text diagrams to an installation of Kroki to display them as images in the preview. Kroki is a free open-source project.

By default the diagram extensions sends your diagrams to the free public cloud instance https://kroki.io but you can install Kroki on your own infrastructure.

[ggrossetie]

I'm fine with your last proposal. What do you think @mojavelinux ?

[mojavelinux]

100% behind you (and to the request at large).

I agree with the statement by @sturtison as a general goal for the Asciidoctor project moving forward:

Privacy and information security is a consideration and our tools should not be "leaky" by default.

Although not relevant here, the default stylesheet does use CDNs by default. I think as long as we are pulling data and not pushing it, that can be a reasonable compromise for privacy. Fortunately, the browser extension has the ability to bundle the assets so even that isn't necessary.

[ggrossetie]

OK! We might mention that Kroki does not sell or share diagrams with third parties ?

[mojavelinux]

It's certainly worth nothing. Though my understanding with these things is that it's more about transparency that data is transferred in the first place. After that, it's the user's choice to establish trust with that service or not. Then the user can opt in once that trust is established.

[ggrossetie]

And since the Kroki API is compatible with the PlantUML server, you could even configure and use a PlantUML server instead: http://www.plantuml.com/ (but in this case only PlantUML diagrams will be converted to images).

Actually it's not true. You can replace http://www.plantuml.com by https://kroki.io but not the other way around.

• http://www.plantuml.com/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000
• https://kroki.io/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000

The reason is that PlantUML is using a custom Base64 encoding but the Kroki extension encodes diagrams using a standard Base64 encoding.