search

asciidoctor / asciidoctor-extensions-lab

A lab for testing and demonstrating Asciidoctor extensions. Please do not use this code in production. If you want to use one of these extensions in your application, create a new project, import the code, and distribute it as a RubyGem. You can then request to make it a top-level project under the Asciidoctor organization.
Other
104 stars 101 forks source link

How do we use these extensions? #35

Closed andreabedini closed 9 years ago

andreabedini commented 9 years ago

Asciidoctor version 1.5.2 mentions, in the help, an option to require ruby modules before running

    -r, --require LIBRARY            require the specified library before executing the processor (using require)
                                     may be specified more than once

I guess this can be used to load these extensions from the command line but I can't find any documentation about this. Especially it's not mentioned either here or here.

ggrossetie commented 9 years ago

Hi @andreabedini there's a blog post explanining how to load extensions from the CLI: http://asciidoctor.org/release-notes/asciidoctor-1-5-0/#spotlight-load-extensions

Let me know if this is working for you, Cheers. Guillaume.

mojavelinux commented 9 years ago

And to bring everything together, here's an example of how you would load the emoji inline macro extension:

git clone https://github.com/asciidoctor/asciidoctor-extensions-lab
asciidoctor -r ./asciidoctor-extensions-lab/lib/emoji-inline-macro.rb your-doc.adoc

Note that the -r should be the relative path from the current directory to the Ruby script that loads the extension. If the extension is bundled and installed as a Ruby gem, like asciidoctor-diagram, then you can simply pass the name, like -r asciidoctor-diagram.

Btw, we need a README for this repository that covers (at least) the following information:

  1. What extensions are available here
  2. How to load an extension from the extension lab

We should also cover how these extensions are organized to help people create new ones.

...and eventually, we need to graduate some extension out of the lab once we determine that they are stable and popular. But we'll cross that bridge when we get to it.

mojavelinux commented 9 years ago

Are you able to load the extensions now @andreabedini? If so, perhaps we can open a new issue to add a proper README.

andreabedini commented 9 years ago

hi @mojavelinux @Mogztter sorry for leaving you hanging. I think I did manage to get them working at some point (and in some way). Mine was perhaps a little complaint on the lack of documentation! :) thanks for all your work. I love asciidoc(or) and I want to see it succeed! especially in academia (my industry) where markdown has already some momentum behind (scholarly markdown).

mojavelinux commented 9 years ago

I think I did manage to get them working at some point (and in some way).

Nice.

Mine was perhaps a little complaint on the lack of documentation! :)

A justified compliant indeed.

I'm going to close this and replace it with an issue to create a proper README.

mojavelinux commented 9 years ago

Closed in favor of #44.