Maven plugin and extensions
Locked
 
|
Hi,
I really hope that I'm not asking something that is obviously documented somewhere that I've simply missed. If so, please forgive me. I'm trying to add some tab navigation and accordion styling to a document getting rendered to HTML. I've gotten fairly close with normal functionality, but I ultimately get stuck because I can't apply a style to the <ul> and <li> items directly. It inevitably ends up being applied to a parent <div> or a child <p>. Of course, I can achieve this using passthrough blocks, but it's pretty cumbersome and I'd like to factor that out of my document. This leads me to think that a custom macro might be the way to go. I don't know Ruby, but I imagine that I can learn from the examples https://github.com/asciidoctor/asciidoctor-extensions-lab/tree/master/lib sufficiently to get something going. However, I have no idea how to get this to run using the maven Asciidoctor plugin which I'm using to render the document. I couldn't figure out how to make the plugin aware of an extension. I also don't know how to build/package an extension so that it's usable by the plugin? I'm sure it's because I'm just not finding/seeing the right documentation, so any pointer would be greatly appreciated. Thanks! |
Administrator
|
Sebastien, Welcome! I recognize this is information that is sorely missing from the README (aka user manual) for the Asciidoctor Maven plugin. First, to solve your problem, it might be as simple as writing a custom template for the unordered list (ulist). == Loading custom templates Custom templates provide a simple way to change any of the HTML that is generated by Asciidoctor. Everything is customizable at this level. To load a custom template, you: 1. Create a directory, let's call it src/docs/templates 2. Create a template file in Slim (the recommended markup language) named ulist.html.slim ---- ul class=role - items.each do |item| li span=item.text - if item.blocks? =item.content ---- For more template examples, see <https://github.com/asciidoctor/asciidoctor-backends>. 3. Specify the path to the template directory in the configuration block of the Maven plugin ---- <templateDir>src/docs/templates</templateDir> ---- 4. Run the build and the template will get used automatically! BTW, we should definitely provide an example of this in the Maven plugin examples <https://github.com/asciidoctor/asciidoctor-maven-examples>. Using a Ruby-based extension is almost as simple. == Loading a Ruby-based extension 1. Create a directory for Ruby-based extensions, let's call it src/docs/extensions 2. Create a Ruby file that contains an extension, called upcase.rb ---- require 'asciidoctor/extensions' Asciidoctor::Extensions.register do block do named :upcase on_context :paragraph process do |parent, reader, attrs| create_paragraph parent, reader.lines.map(&:upcase), attrs end end end ---- 3. Specify the extension path to load in the configuration block of the Maven plugin ---- <requires> <require>${project.basedir}/src/docs/extensions/upcase.rb</require> </requires> ---- 4. Run the build and the extension will get used automatically! You can also create extension in Java, but it's a bit more work. You can get some examples from the extension catalog <http://asciidoctor.org/docs/extensions/>. We want to have some simple examples appear in the extensions lab from AsciidoctorJ <https://github.com/asciidoctor/asciidoctorj-extensions-lab>, but so far it hasn't been done. If you are willing to use Gradle instead of Groovy, you can create an extension directly inside the Gradle build. For an example, see <http://mrhaki.blogspot.com/2015/03/awesome-asciidoctor-use-inline.html>. I hope that helps a bit ;) Abel, it would be great to get the two examples I wrote about into either the README or the examples repository so people have a starting point. Cheers, -Dan On Fri, May 8, 2015 at 3:20 PM, torngat [via Asciidoctor :: Discussion] <[hidden email]> wrote: Hi, Dan Allen | http://google.com/profiles/dan.j.allen |
|
Hi,
Just a couple of notes on what Dan said, I think he meant 'Maven' instead of 'Groovy', About Java extensions, they're not supported yet, still pending and old PR of mine. My apologies :%, details here (https://github.com/asciidoctor/asciidoctor-maven-plugin/pull/151), and here (https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/146). Back to the post, I did not know you could write templates and I was currently writting an old answer based on generating a gem for a ruby extension, so those two exemples are sure good additions. I just created two issues to keep track of them: https://github.com/asciidoctor/asciidoctor-maven-examples/issues/15 https://github.com/asciidoctor/asciidoctor-maven-examples/issues/16 If you want to, you can send the PR's yourseld Sebastien :). But, first of all I'm gona focus on finishing the old PR for java extension. I'm deeply ashmed it is still pending. |
|
Administrator
|
On Sat, May 9, 2015 at 1:06 AM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote: I think he meant 'Maven' instead of 'Groovy', Oops. Yep. That makes more sense :)
For sure! This is definitely one of the key features of the Asciidoctor processor (and even AsciiDoc Python). Being able to control the generated output in a simple way is essential. I just created two issues to keep track of them: Thanks! But, first of all I'm gona focus on finishing the old PR for java extension. I'm deeply ashmed it is still pending. Don't be ashamed. Otherwise, I'd have to be deeply ashamed for the pull requests I haven't gotten to in core :) I'll check out the PR now that you've updated it. Cheers, -Dan Dan Allen | http://google.com/profiles/dan.j.allen |
|
|
Hi Dan and abelsromero,
First off, big thanks for such in-depth (and quick!) answers. It will be my pleasure to contribute examples to the documentation once I get this working. :) Dan, I think you're right that playing around with a slim template might best fit my needs. I've spent the past few hours researching the Slim syntax, putting something together along the lines of your suggestion (trying to add the necessary styles), and then mashing everything together. However, I cannot manage to get the Asciidoctor plugin to render the document. When building my project, I get an error saying that HTML5/Slim backend requires Slim > 2.1.0. ---- Failed to parse source, asciidoctor: FAILED: HTML5/Slim backend needs Slim >= 2.1.0! ---- I already have the gems installed, but I'm not sure that locally installed gems are automatically usable when building with maven and running the Asciidoctor plugin. I tried adding the Slim gem as a runtime dependency to the plugin - no luck. I also tried specifying a <gemPath> value in the plugin's configuration where I had placed the Slim gem - still no dice. I feel like I'm this close, but the proverbial cigar is yet to be had. Any suggestions? Thanks again for the help! Sebastien |
|
Administrator
|
Sebastien, You are now bumping into an intersection of several issues, so I'll try to explain it carefully and give you a rope to climb out to daylight. First, it's important to understand that AsciidoctorJ bundles the necessary gems you need to use Asciidoctor, so you don't need any gems on your system. You don't even need Ruby. In fact, the gems on your system aren't used by default (though there is a way to request that they be used). When the Maven plugin runs, it uses the gems bundled with AsciidoctorJ. The version of Slim that is bundled with AsciidoctorJ 1.5.2 is Slim 2.0.3. Out of the box, you _can_ use custom Slim templates with this version of Slim. However, you _cannot_ use the set of Slim templates provided at https://github.com/asciidoctor/asciidoctor-backends. Those templates require Slim 2.1.0 or above. The reason they require (and enforce) Slim 2.1.0 or above is because they are using the new "include" feature in Slim to keep the templates DRY. You have two option to climb out of this hole. 1) You can write your own Slim 2.0-compatible templates. Basically, start from scratch and you'll know when you are using a feature you can't use. You don't need to change anything else, but obviously it is a lot of work to start from scratch :/ Keep in mind that you only need to provide templates for the nodes you are changing. If a template is missing, Asciidoctor will fallback to using the built-in convert handler for that node. This might be the right solution for you since you only need to customize ulist.html.slim. 2) You can force AsciidoctorJ to use a newer version of Slim. This is a more involved setup, but once it's setup, you'll be able to use any Slim templates you want. To accomplish this, we have to configure Maven to fetch the Slim gem manually, then tell the Asciidoctor Maven plugin to use it. It's similar to what is done to use Asciidoctor Diagram. See <https://github.com/asciidoctor/asciidoctor-maven-examples/blob/master/asciidoctor-diagram-example/pom.xml>. 2a) Add the RubyGems proxy repository to your pom.xml (parent node: project) <repositories> <repository> <id>rubygems-proxy-releases</id> <name>RubyGems.org Proxy (Releases)</name> <url>http://rubygems-proxy.torquebox.org/releases</url> </repository> </repositories> 2b) Add a dependency on the Slim gem (any version you want) (parent node: project) <dependencies> <dependency> <groupId>rubygems</groupId> <artifactId>slim</artifactId> <version>2.1.0</version> <scope>provided</scope> <type>gem</type> <exclusions> <exclusion> <groupId>rubygems</groupId> <artifactId>tilt</artifactId> </exclusion> </exclusions> </dependency> </dependencies> 2c) Add the gem-maven-plugin to download and extract the Slim gem and its dependencies (parent node: project > build > plugins) <plugin> <groupId>de.saumya.mojo</groupId> <artifactId>gem-maven-plugin</artifactId> <version>1.0.10</version> <configuration> <jrubyVersion>1.7.16.1</jrubyVersion> <gemHome>${project.build.directory}/gems</gemHome> <gemPath>${project.build.directory}/gems</gemPath> </configuration> <executions> <execution> <goals> <goal>initialize</goal> </goals> </execution> </executions> </plugin> 2d) Configure the Asciidoctor Maven plugin to add the path to the extracted gems to the classpath (inside the <configuration> element) <gemPath>${project.build.directory}/gems-provided</gemPath> Now the Slim templates from https://github.com/asciidoctor/asciidoctor-backends will just work. I hope that helps! Abel, we may want to think about adding a dedicated tutorial to the Maven plugin repository that details how to use your own gems (which covers numerous use cases). -Dan p.s. I've filed an issue to upgrade Slim in AsciidoctorJ. See <https://github.com/asciidoctor/asciidoctorj/issues/307>. On Tue, May 12, 2015 at 4:27 PM, torngat [via Asciidoctor :: Discussion] <[hidden email]> wrote: Hi Dan and abelsromero, Dan Allen | http://google.com/profiles/dan.j.allen |
|
|
Hi Dan,
Ok, that's what I thought and glad to have it confirmed. :) I didn't realize that I didn't need to include all of the slim templates. I followed your suggestion and removed all but my new template, which I then kept as simple as possible. And... drumroll... I got some of my things to work! I'm sure it could be cleaned up, so if it's ever to be used as an example, I'll need it code-reviewed. But I'll start a side conversation about this as I promised to contribute to the documentation. :) If I may abuse of your time and patience, I have a few more questions: How are the slim templates resolved? I feel like I've really usurped the meaning of "list" to achieve my goals and I think it would be better if I could encapsulate it in a better way. I'm thinking that defining a new block type would be a better way to go, but is it possible to map a new block type to a slim template? Also, is there any way to include an Asciidoctor snippet from a template? For example, how could I get the equivalent of: ---- include::{generated}/response-fields.adoc[] ---- but from within a template. Is there a call that I can make to the main code from the slim template to cause it to be imported? Finally, how/where can I get started to help document some of this? Thanks again! Sebastien |
|
|
Small update:
I found that I can use an "asciidoc:" directive in a Slim template to have some Asciidoc text interpreted, but I keep getting this error when trying to use an include:: directive: (ArgumentError) wrong number of arguments calling `initialize` (1 for 5) when trying ---- asciidoc: include::{generated}/error-example/http-request.adoc[] ---- I've tried with a simple statement like ---- asciidoc: I'm writing some *Asciidoc*! ---- which renders in italics without the 'I': 'm writing some *Asciidoc*! I read in Slim documentation that one has to configure the embedded engines. The presence of "asciidoc:" doesn't make it balk, so I'm guessing the engine is already configured and I'm just not using it correctly. I'm going to keep working at it. I wonder, too, if I'll be able to refer to both Slim and Asciidoc variables within that statement. Something like ---- include::{asciidoc_var}/somefile-#{slim_var}.adoc[] ---- Cheers! Sebastien |
|
Administrator
|
On Thu, May 14, 2015 at 6:31 PM, torngat [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Yep, that's one way to do it. You can also just use the Asciidoctor API directly (for more control) = Asciidoctor.convert("content", base_dir: @document.base_dir, safe: @document.safe) You can pass whatever other options or attribute you need to make it work. but I keep getting this error when trying to use an include:: directive: You are once again dealing with a Slim 2.0.x limitation. You need to put the AsciiDoc source on it's own line, indented. asciidoc: I'm writing some *Asciidoc* using Asciidoctor {asciidoctor-version}!
Yep, it's activated by default.
Yep, both variables are available. However, you are going to have a problem with safe mode, which is set to secure by default in the slim asciidoc context. I'd have to dig in further to see if there's a way to globally change the value (you need to somehow git to the options that Tilt is going to pass to Asciidoctor). I can't remember how at the moment. Though, you can always just use the Asciidoctor API. -Dan Dan Allen | http://google.com/profiles/dan.j.allen |
|
Administrator
|
In reply to this post by torngat
On Thu, May 14, 2015 at 1:17 PM, torngat [via Asciidoctor :: Discussion] <[hidden email]> wrote: How are the slim templates resolved? Slim templates are resolved relative to the templateDirs (in Gradle, template_dirs) option. You can have multiple folders. They are searched in order. By default, Asciidoctor will look for a folder name that corresponds to the templateEngine (in Gradle, template_engine) option. If not found, it looks directly in the template dirs folder. It then looks for that file extension. Each node has a name (i.e., context). This is the name that corresponds to the file it tries to find. For instance, a paragraph block has the name "paragraph". It then looks for the file "paragraph.html.slim" (actually, it looks for something that starts with "paragraph." and ends with ".slim"). If the node is an inline node, then it prepends "inline_" to the search path. When you create nodes (such as in an extension), you can assign any name to the context instance variable. This is an open set. If you use an original name, it will look for a template name that's not in the standard set. That's how you introduce new templates. how/where can I get started to help document some of this? There's an open issue for this. We document currently in the website. See https://github.com/asciidoctor/asciidoctor.org/issues/80 for the issue tracking this particular content. We really need to start with an outline and go from there. Hope that helps a little. Cheers, |
|
|
Hi Dan,
Thanks to your explanations, I've managed to include my external snippet into the main document using my Slim template. I tried both approaches, either using the Slim asciidoc: directive as well as a direct call to the API. I was able to get the API call to work if I passed the content of the asciidoc file directly using IO.read(): ---- = Asciidoctor.convert(IO.read("path_to_my_file"), base_dir: @document.base_dir, safe: @document.safe) ---- I haven't tried, but I'm guessing that if that included file contained its own "include::" macros, those might not get resolved... However, with the Slim directive, all I could ever get was the path+file name (and not the contents) to show as plain text. Could this have something to do with the safe mode you mentioned? I echo'ed the @document.safe within the Slim template and it says it's already set to 0. I'm not setting this anywhere that I'm aware of, so I'm not sure where it could be coming from. Slim directive: ---- asciidoc: include::"path_to_my_file" ---- In any case, with the API it works as I hoped it would, even though I fear I've used a bit of brute force. I'm going to continue digging to see how I could clean it all up a bit better. I'll probably post follow-up question(s). :) Thanks again for all the help! |
|
|
In reply to this post by mojavelinux
Hi Dan,
I'm really sorry for being obtuse, but I'm still not clear on how I can assign a name to a new template such that it is recognized by Asciidoctor as something valid. Using the "yell" example from the user manual, how can I do it if I want to use a Slim approach instead of a Java based extension? Basically, how does "yell" get registered? Not being sure how to go about it, I created a Slim templates called "block_yell.html.slim" and tried variations like this [yell] Hey! Ho! Let's go! [name=yell] Hey! Ho! Let's go! The first warns of an invalid style. The second simply outputs the string and doesn't use the template. I have also tried variations with an open block, and inline templates, but to no avail. Is this possible? Thanks, Sebastien |
|
Administrator
|
In reply to this post by torngat
Sebastien, I'm glad to hear you got it working. Sometimes, _a_ solution is better than no solution :) asciidoc: include::"path_to_my_file" ---- Aren't you missing the closing square brackets? Or did you just type it incorrectly in the e-mail message? I haven't tried, but I'm guessing that if that included file contained its own "include::" macros, those might not get resolved... They should work as expected. I'll probably post follow-up question(s). :) We'll be here! -Dan On Tue, May 19, 2015 at 11:38 AM, torngat [via Asciidoctor :: Discussion] <[hidden email]> wrote: Hi Dan, Dan Allen | http://google.com/profiles/dan.j.allen |
|
|
Hi Dan,
Sorry, they were missing in my message but I had them in code. FYI, I tried the following variations (blank lines only for readability in this post): ---- / example 1 - this works = Asciidoctor.convert(IO.read("#{attr 'generated_dir''}/example/response-fields.adoc"), base_dir: @document.base_dir, safe: @document.safe) / example 2 - this gives an HTML link to file "/my/generated_dir/example/response-fields.adoc" asciidoc: include::#{attr 'generated_dir'}/example/response-fields.adoc[] / example 3 - this shows plain text path "/my/generated_dir/example/response-fields.adoc[]" asciidoc: include::"#{attr 'generated_dir''}/example/response-fields.adoc[]" ---- Aside from example #1 that works, the only one that appears to be doing something is #2 where the result is a URL to the document instead of the content of the document being included. I toggled the ":allow-uri-read:" property in the parent document but that didn't change anything. FYI, the document's safe mode is already 0. Cheers! Sebastien |
|
Administrator
|
This proves the problem at hand...that the safe mode of the asciidoc handler in Slim is defaulting to secure and cannot be changed (or I have to remember how to pass default options from Tilt to Slim). The issue is actually with Tilt, not Slim as Slim is just delegating to Tilt.
I think the problem here is the double quotes. Asciidoctor isn't going to recognize that line.
Yes, but the document safe mode is not 0 inside the asciidoc directive, which is where the problem lies. You can see this by using: asciidoc: {safe-mode-name} You should see that is "secure" and not "safe". One quick way to solve this problem is to create a file called "set-safe-mode.rb" with the following content: [source,ruby] ---- require 'slim' Tilt['slim'].options[:asciidoc] = { safe: :safe } ---- Then load it when you call Asciidoctor $ asciidoctor -r ./set-safe-mode.rb -T /path/to/templates doc.adoc However, this made me realize that we should be setting the safe mode on this engine to match the safe mode of the document. I've filed an issue https://github.com/asciidoctor/asciidoctor/issues/1347. Cheers, -Dan Dan Allen | http://google.com/profiles/dan.j.allen |
«
Return to Asciidoctor :: Discussion
|
1 view|%1 views
| Free forum by Nabble | Edit this page |