Git Product home page Git Product logo

asciidoctor-plantuml's Introduction

Asciidoctor Plantuml Extension

Tests Latest Release

Asciidoctor PlantUml is an extension that enables you to add PlantUML diagrams to your AsciiDoc documents.

This extension differs from others like Asciidoctor Diagram and AsciiDoc PlantUML filter in that this extension does not include PlantUML jar files. Instead it depends on the availability of an external PlantUML server.

Installation

Asciidoctor PlantUml is a RubyGem and can be installed via gem or bundle commands:

$ gem install asciidoctor-plantuml

Creating a diagram

A diagram is written inside an open block inside any asciidoc file:

[plantuml, format="png", id="myId"]

alice → bob : hello bob → alice : hello


Note
You can omit the @startuml/@enduml delimiters. The extension adds them if missing.
Tip
You can create any diagram type supported by PlantUML: sequence, usecase, class, activity, etc.
Warning
You must use an open block, that is delimited by two - instead of four as in a literal block.

The above example is substituted by the following HTML snippet when processed by this extension:

<img id="myId" class="plantuml" src="http://localhost:8080/png/S3dx3fjsaso3d" />

PlantUML Server

By default the image source follows the following URL pattern:

PlantUML URL Pattern
<server base uri>/<format>/<encoded diagram>

The <server base uri> by defaults is http://localhost:8080/plantuml and can be changed using the following code:

require "asciidoctor-plantuml"

Asciidoctor::PlantUml.configure do |conf|
  conf.url = "http://my-private-server:8080"
end

In 2020 the plantuml.com server changed the URL encoding. Now you’ll need to add a small string to signal the encoding. You can enable the new behavior like this:

require "asciidoctor-plantuml"

Asciidoctor::PlantUml.configure do |conf|
  conf.url = "https://www.plantuml.com"
  conf.encoding = 'deflate'
end

The <format> is taken from the block format attribute. It defaults to png and can take any of png, txt and svg.

The <encoded diagram> is generated automatically by this extension. This is the diagram string compressed and encoded in a format that the PlantUML server understands.

Diagram Attributes

There are some attributes you can add to the block to customize how the diagram is displayed:

  • id: Sets the id attribute of the img element.

  • alt: Sets the alt attribute of the img element.

  • width: Sets the width attribute of the img element.

  • height: Sets the height attribute of the img element.

  • format: Sets the format of the generated image. Can be either png, svg or txt.

Using Asciidoctor Cli

To load the asciidoctor-plantuml extension when using the asciidoctor command line tool you can use the -r flag:

asciidoctor -r asciidoctor-plantuml sample.adoc

If you want to change the default PlantUML server you can use PLANTUML_URL environment variables:

PLANTUML_URL="https://my-private-server:80/" asciidoctor -r asciidoctor-plantuml sample.adoc

Installing PlantUML Server

Docker

The simplest way to start a PlantUML server is using docker:

docker run -d --name plantuml -p 8081:8080 plantuml/plantuml-server:jetty

Source

In Ubuntu first you need to create a plantuml.war file from the source code:

sudo apt-get install tomcat7 graphviz openjdk-7-jdk git-core maven
git clone https://github.com/plantuml/plantuml-server.git
cd plantuml-server
mvn package

Then copy the plantuml.war file generated when building the package (mvn package) to the Tomcat applications folder:

sudo cp plantuml.war /var/lib/tomcat7/webapps/plantuml.war
sudo chown tomcat7:tomcat7 /usr/share/jetty/webapps/plantuml.war
sudo service restart tomcat7

After restarting Tomcat the application will be running on the server port 8080. You can change the port and other parameters in the /etc/tomcat7/server.xml file.

You may also need to set the JAVA_HOME variable in the /etc/defaults/tomcat7 file if you have the java runtime in a non-standard place.

asciidoctor-plantuml's People

Contributors

aerostitch avatar dependabot[bot] avatar digitalmoksha avatar ggrossetie avatar gogainda avatar gururajrkatti avatar hsanson avatar rmetzler avatar vinise avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar

asciidoctor-plantuml's Issues

The subs attribute should be honored

Here's an example:

:action: hello

[plantuml,subs=+attributes]
----
alice -> bob : {action}
----

In the above example, {action} should be replaced/substituted by hello.
You can use the following code to do that:

subs = attrs['subs']
content = parent.apply_subs(content, parent.resolve_subs(subs)) if subs

Recover rubygems.org account.

Let my old email domain expire without updating the rubygems.org account with my new email and now I cannot update the this gem.

This issue is to prove that I own and maintain this repo and the asciidoctor-plantuml gem in it.

It should be possible to declare a PlantUML diagram in a literal block

Currently, the extension only works on listing blocks. Since Asciidoctor Diagram recognizes both literal and listing blocks I think it would be great to also enable this extension on literal blocks.
I also believe that a literal block is semantically more accurate than a listing block (but it might be subjective).

I think the main benefit would be that users won't have to update their document if they want to use Asciidoctor Diagram or this extension.

What do you think?

Specifying plantuml.jar

Hi!
I was wondering about a way of specifying a concrete plantuml.jar file for asciidoctor-pdf. The one coming with asciidoctor-pdf seems an older file than the version found in plantuml.com. Not being much of a ruby programmer I was looking through .rb for asciidoctor-pdf, and could not find any obvious parts...

Thanks!

New tag needed!

Could you please create a new version tag including latest changes?

Project including your lib are still not up-to-date and won't have the updates until there is a new version

Thanks

PlantUML: "The plugin you are using seems to generated a bad URL." on official PlantUML server

The official plantuml.com server changed to URL format. Gitlab (and probably some other webapps) use asciidoctor-plantuml to create an image URL. Since the URL was changed, plantuml images are broken on Gitlab.

broken example from your testsuite

I copied the URL from your testsuite and changed the host

GENURL = 'http://localhost:8080/plantuml/png/U9npA2v9B2efpStX2YrEBLBGjLFG20Q9Q4Bv804WIw4a8rKXiQ0W9pCviIGpFqzJmKh19p4fDOVB8JKl1QWT05kd5wq0'

you can see this is broken

https://www.plantuml.com/plantuml/png/U9npA2v9B2efpStX2YrEBLBGjLFG20Q9Q4Bv804WIw4a8rKXiQ0W9pCviIGpFqzJmKh19p4fDOVB8JKl1QWT05kd5wq0

broken

This works

Just by adding ~1 it's fixed

https://www.plantuml.com/plantuml/png/~1U9npA2v9B2efpStX2YrEBLBGjLFG20Q9Q4Bv804WIw4a8rKXiQ0W9pCviIGpFqzJmKh19p4fDOVB8JKl1QWT05kd5wq0

good

Links

Bump nokogiri from 1.13.4 to 1.13.6

Security advisor on nokogiri 1.13.4:

Note this gem uses nokogiri only for running the tests and it is never used in the gem itself. These security advisors should not pose a risk to users of the gem.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.