Preview asciidoctor diagrams

[rotty3000]

Is there diagram rendering support?

[mojavelinux]

This is related to https://github.com/asciidoctor/asciidoctor.js/issues/64.

I put together a prototype of a dot extension (though not using Asciidoctor Diagram), but it's very alpha at this point. See https://github.com/opendevise/neo4j-asciidoctor-extensions/blob/master/extension-dot-block.rb

The tricky part about diagram extensions in Asciidoctor.js is that many of the diagramming tools themselves are built in Java or native code. The native code can be ported to JavaScript using emscripten (an LLVM to JavaScript compiler), which is what the dot extension I linked to uses. Porting Plantuml is much harder. The best strategy here is to focus on specific formats and see if we can get them converted.

[ggrossetie]

JavaScript implementation:

• https://github.com/mdaines/viz.js/
• https://github.com/cpettitt/dagre
• http://plantuml.sourceforge.net/codejavascript.html

http://ditaa.sourceforge.net/

[mojavelinux]

https://github.com/mdaines/viz.js/

This is the one transpiled using emscripten (which is practically like magic). Neo did report there were some deficiencies in processing larger diagrams, but I'm not sure of the details right now.

[bornio]

What about http://bramp.github.io/js-sequence-diagrams/ ?

[ggrossetie]

@bornio It's a good idea for an extension: https://github.com/asciidoctor/asciidoctor-extensions-lab (you can give it a try if you want)

[mbajolek]

I've been playing with plantuml a bit and was able to get asciidoctor-chrome-extension supporting plantuml syntax. How does it work? a) during .ad file load/reload it extracts plantuml tags: @startuml .... @enduml b) replace tags with macro: image::http : //www.plantuml.com/plantuml/img/zipped_uml_and_base64 c) renders .ad content

Here is what I did/hacked ... please note I'm really not JS developer :)

1. Get app/js/asciidocify.js from this git commit: https://github.com/mbajolek/asciidoctor-chrome-extension/commit/97a2b14b4cc68d27a55c2b097a10d53778ecc8af
2. Copy to your asciidoctor-chrome-extension directory e.g.: "c:\Users\mac\AppData\Local\Google\Chrome\User Data\Default\Extensions\iaalpfgpbocpdfblpnhhgllgbdbchmia\1.5.2.120_0\js\asciidocify.js"
3. Reload your extension ... I usually disable/enable it in chrome://extension page

4. Put into your .ad file a diagram based on plantuml notation e.g.:

   @startuml [Generating and Compiling JAXB ,align="center"]
   start
   :read *.xsd files;
   note left
   this is note
   end note
   
   :read *.xjb files;
   note left
   this is note
   end note
   
   :maven-jaxb2-plugin:generate;
   note left
   generate JAXB bindings (java classes)
   based on .xsd files
   end note
   
   :Compile;
   note right
    compile with tycho-compiler-plugin
   end note
   
   stop
   @enduml

5. If everything works well ... enjoy :)

[mojavelinux]

Very cool.

However, I think it's better to do this is a proper block extension. We want to avoid parsing AsciiDoc in an ad-hoc way because it leads to behavior that doesn't respect the structure of the document. I love the idea of diagrams working in the chrome extension, though, so I definitely want to see this move forward.

My recommendation is to write the extension in Ruby with transpiling in mind, transpile it, then load it into the chrome extension. I'm sure @Mogztter can help you with that process as he's done it for multiple extensions now.

[jxxcarlson]

Yes! Diagrams!!

On Jun 11, 2015, at 3:10 PM, Dan Allen notifications@github.com wrote:

Very cool.

However, I think it's better to do this is a proper block extension. We want to avoid parsing AsciiDoc in an ad-hoc way because it leads to behavior that doesn't respect the structure of the document. I love the idea of diagrams working in the chrome extension, though, so I definitely want to see this move forward.

My recommendation is to write the extension in Ruby with transpiling in mind, transpile it, then load it into the chrome extension. I'm sure @Mogztter https://github.com/Mogztter can help you with that process as he's done it for multiple extensions now.

— Reply to this email directly or view it on GitHub https://github.com/asciidoctor/asciidoctor-chrome-extension/issues/79#issuecomment-111244671.

[mbajolek]

The only problem with plantuml in this context is that in theory it requires GraphViz package installed on a workstation. The hack I've done is simply taking advantage of plantuml web/rest service to download generated images/diagrams and embedd them into ad document.

[mojavelinux]

@mbajolek I agree with the approach, but I still think even that part should be wired to the processor using a formal Asciidoctor extension. In other words, it's fine to use the web service to avoid the local install. I'd just like to see it done in a way that is integrated into Asciidoctor rather than as a global search and replace. The later approach lacks context and runs the risk of not honoring the the integrity of the document. After all, that's why we created the extension API.

[mbajolek]

I apologize for later response ... obviously my global search/replace is a hack rather than something that should be used as feature implementation :)

To give you more context why I've ever looked at this ... I'm using asciidoc maven plugin for documenting one of the projects I'm participating. I really wanted to have either plantuml or umlet like diagrams in my doc ... inside ... not somewhere outside. I did similar hack as a MOJO that does global search/replace and extracts @startuml tags to a separate files, replaces with image:: macro, than launch plantuml maven plugin to generate diagram images and then launch asciidoc maven phase. For writing documentation I use IntelliJ with both: asciidoc and plantuml plugins that apparently work well together. However I need something for team members that don't use IJ ... that's why I hacked chrome plugin :) Recently I just noticed the extension API for asciidoc that I think can be used for the integration I mentioned above ... am I right?

I will take a look on how you guys are implementing these kind of feature and try to do on my own. I also assume that however plantuml is integrated it should be consistent across asciidoc implementations: mojo, chrome-ext, ruby .... etc. correct?

[bbucko]

Is this approach the correct one: https://github.com/bbucko/asciidoctor-chrome-extension/commit/97fa4b8929b46374d8ed1f74ebdb341f1826b7a6 ?

[mojavelinux]

@bbucko Indeed. That looks like your on to it! However, I'd like to make sure we are able to trace it back to the source from which it was cross compiled. Could you add the Ruby source to the extensions-lab repo (https://github.com/asciidoctor/asciidoctor-extensions-lab). @Mogztter has been compiling extensions for Chrome out of there.

[mojavelinux]

Recently I just noticed the extension API for asciidoc that I think can be used for the integration I mentioned above

Correct.

I also assume that however plantuml is integrated it should be consistent across asciidoc implementations

Ideally, yes. But the external dependency makes this goal a challenge. Ideally, we could extend Asciidoctor Diagram to delegate to a service / server in certain environments (like the browser) where access to tools installed on the system is not permitted.

Keep in mind Asciidoctor Diagram is the official way of using PlantUML in the Asciidoctor ecosystem. We just haven't completely sorted out the Asciidoctor.js integration story yet. But I do think that eventually we will (in some form or fashion).

[bbucko]

@mojavelinux I already did that: https://github.com/bbucko/asciidoctor-extensions-lab/commit/b1a21f04836c9ac7e953d9aead4e9ce42df04439

I'll prepare PR for review.

[mojavelinux]

\o/

[mojavelinux]

One question. Is deflate.js a library we can link to (or manage with Bower?) Or is it a bunch of stuff coming from different places?

[bbucko]

I don't think so. I "borrowed" JavaScript provided by PlantUML team to ensure compatibility. They're using this library: https://github.com/johan/js-deflate.

[mojavelinux]

Gotcha. I saw the link in the comments. Let's just make sure it's clear to someone auditing the code where things came from to avoid any trouble ;)

[bbucko]

Will do.

[bbucko]

Done. https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/52 Once the PR is approved I'll create similar one in this repo.

[mojavelinux]

Excellent! I'll have a look at it tonight.

[sarod]

Any progress on this? It would be very convenient to have diagrams work out of the box in the live preview

[ggrossetie]

Yes that would be great!

@bbucko @mojavelinux What is the current status of https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/52

Recently Alex Soto mentioned this library (mermaid) but I didn't try to integrate it with Asciidoctor.js With this library we could potentially do the preview without using a remote server.

[MatthiasNeuhaus]

I really like this extension. Would be great if you would work on this topic. plantuml would be relay nice!

[mbajolek]

I still use @bbucko 's fork for Chrome browser: https://github.com/bbucko/asciidoctor-chrome-extension/archive/master.zip ...

[ggrossetie]

Interesting! @bbucko could you please make a pull request against the master branch ? Did you use https://github.com/pepri/plantuml-viewer ?

[mbajolek]

If I need just plantuml designer/viewer I use one of:

• http://www.planttext.com/planttext
• Intelij plugin

But @bbucko 's fork is more than that .... it actually allows me to work on my asciidoctor documentation with plantuml diagrams in inline mode.

[MatthiasNeuhaus]

Hello together, so what is missing @Mogztter (don't want to hurry :roll_eyes: )? As far as I can see @bbucko has a PR against master branch of asciidoctor-extensions-lab. Do you want him to open one directly to master of asciidoctor-browser-extension? Sorry if I get things wrong, I'm quite new to github :blush:.

[svenn71]

I landed here when I was looking for asciidoctor-diagram support in atom asciidoc-preview.

[ggrossetie]

Hello @MatthiasNeuhaus,

What we need is an extension that can run on a browser. I took some ideas from @eshepelyuk and from https://github.com/pepri/plantuml-viewer to create an extension and here's the result:

This extension relies on a PlantUML server so you need to have an Internet access or a local PlantUML server (as described here: https://github.com/eshepelyuk/asciidoctor-plantuml.js/blob/master/README.adoc#plantuml-server

I will open a pull request in a few days 😃

[Skilly]

@Mogztter Awesome!!

[mojavelinux]

At this point, I'm certain that the extension lab isn't the right place for the PlantUML extension. It deserves to be a top-level extension. I'm glad to see some efforts are materializing. I'm hoping we'll be able to see asciidoctor-plantuml.js become the official PlantUML support for Asciidoctor.js. That's where the effort should be focused, IMO.

I'll add that support for PlantUML is of enormous importance based on the demand I've observed. It will not only be useful for a vast number of users, it should help to promote the browser extension and anything else that uses it. Just look at the download numbers for asciidoctor-plantuml.js already.

[mojavelinux]

On a side note, I'm also interested to see if Asciidoctor Diagram has a story in the Asciidoctor.js world. I see that more as a long-term project, so we don't want that research to hold up support for PlantUML. But given how much engineering has gone into Asciidoctor Diagram, and how many tools it supports, I'm certain that figuring out how to bridge to it will have value.

[ggrossetie]

It's coming in the next release!

[ggrossetie]

I'm closing this issue since we can now render PlantUML diagram 🎉 🎉 🎉

[metametadata]

Should it work for included diagrams too? This still doesn't work:

plantuml::xxxx.puml[format=png]

[ggrossetie]

Hello @metametadata,

No currently you should use a block but you can open an issue here: https://github.com/eshepelyuk/asciidoctor-plantuml.js to add a block macro.