Victor,
The most pragmatic way to look at GitHub is as a viewer of static AsciiDoc files (no extensions and vanilla HTML).
Fortunately, there's enough flexibility in AsciiDoc to get diagrams to display by introducing a bit of logic. Both solutions I've come up with leverage preprocessor conditionals.
The first approach relies on an automated step to materialize the diagram using either a commit hook or CI build so GitHub can reference the generated, static image. Here's how you'd write the AsciiDoc:
ifdef::env-github[image::diagram-classes.png[Diagram classes]]
ifndef::env-github[]
[plantuml,diagram-classes,png]
....
class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock
BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
....
endif:[]
It's up to you to implement the commit hook or CI build part :)
Obviously, the diagram-classes.png image won't exist until you execute Asciidoctor the first time. However, each time you change the diagram, the linked image will get updated. So you get the best of both worlds.
The second method relies on something like
http://www.gravizo.com (which is awesome btw). This solution isn't going to look as pretty, but has the benefit of not relying on an automated build step.
:diagram-source: pass:[class BlockProcessor; \
class DiagramBlock; \
class DitaaBlock; \
class PlantUmlBlock; \
BlockProcessor <|-- DiagramBlock; \
DiagramBlock <|-- DitaaBlock; \
DiagramBlock <|-- PlantUmlBlock]
ifdef::env-github[image::<a href="http://g.gravizo.com/g?@startuml;{diagram-source};@enduml[Diagram">http://g.gravizo.com/g?@startuml;{diagram-source};@enduml[Diagram classes]]
ifndef::env-github[]
[plantuml,diagram-classes,png,subs=attributes+]
....
{diagram-source}
....
endif:[]
The only problem with this approach is that Asciidoctor Diagram does not currently honor the "subs" attribute. I'll file an issue for that.
(You may have to deal with some URL encoding issues to get that to work perfectly. It would be far better of gravizo relied on a base64-encoded string because passing arbitrary characters through a query string can be problematic. Of course, you could always stand-up your own application that mimics gravizo)
gravizo also supports linking to a diagram source. That's probably a much cleaner solution than using an attribute reference. I'm sure you can imagine how it would work.
The same two solutions would also work for browser-based previewing (env-browser).
If there's a change to core that would make any of this easier, of course I'd be open to making it.
Cheers,
-Dan
Locked
Mar 23, 2016; 5:06pm
