search

asciidoctor / asciidoctor-diagram

:left_right_arrow: Asciidoctor diagram extension, with support for AsciiToSVG, BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag), Ditaa, Erd, GraphViz, Mermaid, Msc, PlantUML, Shaape, SvgBob, Syntrax, UMLet, Vega, Vega-Lite and WaveDrom.
http://asciidoctor.org
MIT License
442 stars 107 forks source link

When/can/how github.com and GitLab.com auto-render ditaa and plantuml from .adoc files? #274

Closed johnnyutahh closed 4 years ago

johnnyutahh commented 4 years ago

When/can/how github.com auto-render ditaa and plantuml blocks when viewing (from github.com) .adoc files?

I suspect this is a FAQ, but I could not find a previous answer.

Details

I want github.com [2020-03-22 edit: and GitLab.com] to render images in an .adoc like the following example but without resorting to hard-coding the image references (as in image::sample-ditaa-diagram.png[]).

https://github.com/asciidoctor/asciidoctor.org/blob/master/news/plain-text-diagrams-in-asciidoctor.adoc

pepijnve commented 4 years ago

@johnnyutahh that's a feature request for GitHub itself, which I don't have any control over whatsoever. There's nothing inherently preventing GitHub from doing this. You could try contacting GitHub support with this question.

johnnyutahh commented 4 years ago

Thanks much @pepijnve for the timely reply, very appreciated.

@johnnyutahh that's a feature request for GitHub itself, which I don't have any control over whatsoever. There's nothing inherently preventing GitHub from doing this. You could try contacting GitHub support with this question.

Yes, of course, I'm aware of that. What I'm therefore effectively asking: is there some way (some configuration, tweak, etc that y'all know that I do not) to get github.com to auto-render the asciidoctor-diagram graphics (particularly for plantuml or ditaa)? And if it does not work, it'd be interesting to see what if anything y'all have tried to 1) "tweak" it work or 2) ask github.com to do something about it. (They already do .adoc renderings... so there was some sort of asciidoc/asciidoctor integration done somewhere along the way, and do we know which personnel made that happen on the github side?)

I'm assuming by your above reply the answer is "we (asciidoctor) know of no way to make that work, and we're respectfully not interested in and/or we do not have resources to expend for additional effort to make it work or investigate with our github contacts to make it work." Which all makes perfect sense. Knowing whatever the background is will help me to determine next steps.

(And/or: y'all are trying to keep your open-issue queues as small as possible. Which is also understandable.)

Eventually, github.com should be interested in this. It seems bloody damn valuable to have text-based-source graphics capability in their view renderings. If we could reach the right person (possibly product-manager and/or VP-ish kind of level) at github who's thinking and/or care about this kind of feature (especially it means something more to their financial bottom line), we might be able to help motivate them make it happen.

"By default," per my initial testing, it does not work.

pepijnve commented 4 years ago

It's more a matter of having no contacts at GitHub to request this and having no influence whatsoever over what the GitHub team does. I have no idea how the GitHub code uses asciidoctor or asciidoctor-diagram exactly. I can't give you any advice here. Maybe (really big maybe) @mojavelinux can tell you a bit more.

If you're trying to get in touch with GitHub product management, then this project's issue tracker is simply the wrong place for that. I do not work for GitHub and do not have any points of contact there. I doubt anyone from the GitHub development team monitors this project.

mojavelinux commented 4 years ago

I have contacts at GitHub, but that's not how GitHub works. No matter who you know, GitHub requires that you communicate via support. If enough requests are made through that channel, they may (or may not) decide to implement a feature. I don't see that changing.

You're free to make the case and perhaps it will make a difference. We will most certainly lend our voices in support.

It seems bloody damn valuable to have text-based-source graphics capability in their view renderings.

We wholeheartedly agree.

On another note, we have had success getting these types of changes on GitLab. Very recently, support was added for both font-based icons and PlantUML diagrams.

johnnyutahh commented 4 years ago

Very helpful feedback, thanks very much @pepijnve and @mojavelinux for the feedback.

On another note, we have had success getting these types of changes on GitLab. Very recently, support was added for both font-based icons and PlantUML diagrams.

That's super good to know. I plan to look into that.

Thanks again.

johnnyutahh commented 4 years ago

On another note, we have had success getting these types of changes on GitLab. Very recently, support was added for both font-based icons and PlantUML diagrams.

@mojavelinux - I tried (below) the PlantUML render on GitLab with no success. Any thoughts?

https://gitlab.com/johnnyutahh/software-systems-docs/-/blob/master/z-sandbox/diagram-test.adoc

mojavelinux commented 4 years ago

I could be wrong, but I think it has to be a listing block (though it should be supporting the literal block). See https://docs.gitlab.com/ee/administration/integration/plantuml.html#creating-diagrams

johnnyutahh commented 4 years ago

Right. Changing plantuml list block delimiters from .... to ---- solves the GitLab problem.

https://gitlab.com/johnnyutahh/software-systems-docs/-/blob/master/z-sandbox/diagram-test.adoc

Thanks Dan for your help on this, really appreciated.