JBoss Forge Asciidoctor addon

install-and-run.adoc

JBoss Forge Asciidoctor addon

Table of Contents

• Install the Asciidoctor addon
• Configure Asciidoctor for Maven projects
  • Html5 output
  • PDF outpout
  • Process AsciiDoc in a Maven site using Asciidoctor
• Process Asciidoc file with shell command

Note	JBoss Forge needs to be installed. More info on the JBoss Forge website.

Install the Asciidoctor addon

• Run Forge

  forge

• Install the jboss forge asciidoctor addon

  addon-install-from-git --url https://github.com/mgreau/asciidoctor-forge-addon.git --coordinate org.jboss.forge.addon.asciidoctor:asciidoctor-forge-addon,1.0.0-SNAPSHOT

Configure Asciidoctor for Maven projects

Html5 output

• create a new forge project

  project-new --named myproject

• setup asciidoctor for Html5 outpout

  asciidoctor-setup --useAsciidoctorDiagram -a toc=right sourceHighlighter=coderay icons=font sectanchors

• build the project with forge

  build

• open the generated file

  open target/generated-docs/manual.html

PDF outpout

• create a new forge project

  project-new --named myproject

• setup asciidoctor for PDF outpout

  asciidoctor-setup --converter pdf -a toc sectanchors idprefix=a_ idseparator=_

• build the project with forge

  build

• open the generated file

  open target/generated-docs/manual.pdf

Process AsciiDoc in a Maven site using Asciidoctor

• create a new forge project

  project-new --named myproject

• add the maven-site-plugin with the Asciidoctor Maven plugin configuration

  asciidoctor-generate-site

• generate the maven site

  mvn site:site

• open the generated file

  open target/site/hello.html

Process Asciidoc file with shell command

forge
track-changes
asciidoctor -a stylesheet! src/docs/asciidoc/sample.adoc

Then open the sample.adoc file and update the content, save it and wait a few time until the asciidoctor processor converts the sample.adoc to a sample.html output.

the command to create a new project is:

    project-new --named myproject

fixed, thanks

Overall, this is great! Solid work.

I'd like to see the backend name match what gets passed to Asciidoctor. In this case, it would be "pdf" instead of "PDF" (or make it can insensitive so either is accepted).

I'm also curious why you use colon (:) to separate key/value attribute pairs instead of equals (=). Would you be open to changing that? Also, could you support the -a alias to pass multiple attributes so it works like the Asciidoctor CLI?

asciidoctor-setup --converter pdf -a sectanchors -a idprefix=a_ -a idseparator=_

I just tried it, worked the first time. Amazing.

Could you upgrade Asciidoctor Diagram to 1.2.1 by default?

Yes, you're right, I will try to be as close as possible to the Asciidoctor CLI.

I've updated code and doc :

• upgrade to Asciidoctor Diagram 1.2.1
• lowercase the converter name (docbook, html5, pdf)
• key/value separated by =

So, you can execute the command below :
asciidoctor-setup --converter pdf -a sectanchors idprefix=a_ idseparator=_

I don't know if it's possible to support severals times the -a alias in the same command.
Maybe @gastaldi can help on this ?

Hi @mgreau,

That's a good question. We use Aesh as the underlying shell impl and I guess it should work. If it does not, please open a JIRA and we can have a look at it.

Great job!

Hi and thanks :)
I confirm that it doesn't work, indeed only the first one is considered, the others are ignored.
OK, I will open a JIRA.

Great job Maxime!

Scope creep warning ahead:

I was thinking that it would be awesome if this plugin would allow you to run the asciidoctor command inside the forge shell. Rather than shell out to the Ruby command, the asciidoctor command in Forge would delegate to AsciidoctorJ. That way, all you would need to run asciidoctor from the CLI is to launch Forge and install this plugin. wdyt?

forge
asciidoctor src/docs/asciidoc/sample.adoc

We could even wire it into a file monitor so it continuously runs as the source document changes. That would be so slick?

Thanks.

I was thinking that it would be awesome if this plugin would allow you to run the asciidoctor command inside the forge shell.

Yes, it's a cool feature :)
I will take a look and let you know how it goes

BTW, do you think it makes sense to delete the "--toc" and "--sourceHighlighter" options since all attributes can be passed with the "--attributes" option ?

This is AWESOME! I think that the --toc and --sourceHighlighter shortcuts are fine. It's nice to have some help to easily enable features that would otherwise require looking things up in the documentation.

Why isn't this on the forge website yet?? :) http://forge.jboss.org/document/share-your-addon-on-the-forge-website

@lincolnthree thanks !
I think that before sharing it I have to implement the "maven site configuration" feature and we have to validate the plugin name and move the project to the final github location.
Wdyt?

I've updated code, tests and doc :

• implement the asciidoctor-generate-site command to configure the "maven-site-plugin" with the asciidoctor plugin
• asciidoctor-setup : handle the fact that asciidoctor version is different that asciidoctor-maven-plugin
• add more tests
• upgrade to JBoss Forge 2.11.0.Final

@mojavelinux @gastaldi @lincolnthree hi guys, a first version for the "asciidoctor shell" feature with resource monitor is available on github. So you can test it with the following commands :

forge
track-changes
asciidoctor -a stylesheet! src/docs/asciidoc/sample.adoc

Then open the sample.adoc file and make any update in the document, save it and wait a few second until the asciidoctor processor converts the sample.adoc to a sample.html output.

I really like the asciidoc shell command, but something inside me really wants it to be asciidoctor. Perhaps you can simply allow either name?

Oups, it was an error in the documentation :)
Sure, I've created an asciidoctor shell command, Asciidoctor FTW !
Thank to your message, I now understand why my unit test has failed :)