have asciidoctorj output html to be include in jekyll generated site ?
Locked
have asciidoctorj output html to be include in jekyll generated site ?
 
|
I'm trying to figure out how to have my guide for github.com/jbangdev/jbang (currently just the readme.org) built with asciidoctorj to be output in a format I can include in my jekyll based website at github.com/jbangdev/jbang.dev.
I was wondering there was way to have it generate the same output but just without the <html> and ohter header info, but that will of course get into issues when doing multiple pages html rendering etc. Any ideas/suggestions on how to best to do this hybrid so the content can fit into the overall style/structure of the website without having to give up on asciidoctorj nor jekyll ? :) |
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
There's the ''headerFooter'' option (in `OptionsBuilder` class). But not sure how to integrate with a jekyll site without resorting to GH-Action scripting. You could try with https://github.com/asciidoctor/jekyll-asciidoc or some Gh-Action scripting but it feel too much "yak shaving" to my taste. If the docs are in the code repo and the site in another place, you could rework them with Antora. There will be extra tasks like spliting the docs, definint a UI theme and integrating a search solution (eg. https://github.com/Mogztter/antora-lunr), but at least those are docs-related efforts, not custom scripts. If you are willing to consider, drop by https://gitter.im/antora/users with any question, you'll find other RedHat members working on antora sites, they should be able to help you also. |
Re: have asciidoctorj output html to be include in jekyll generated site ?
Administrator
|
Given you're already using Jekyll with the Jekyll AsciiDoc plugin for the website, I don't see why you wouldn't just include readme.adoc as part of the source for that site. If you want it to be downloaded automatically, use a remote include (like https://cdn.jsdelivr.net/gh/jbangdev/jbang/readme.adoc) and enable the allow-uri-read attribute to give Asciidoctor permission to download it. If you want to avoid this hacky, I second Abel's point of using Antora. Perhaps there's still an opportunity to make the switch. -Dan On Sat, Nov 21, 2020 at 1:03 AM abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote: There's the ''headerFooter'' option (in `OptionsBuilder` class). But not sure how to integrate with a jekyll site without resorting to GH-Action scripting. You could try with https://github.com/asciidoctor/jekyll-asciidoc or some Gh-Action scripting but it feel too much "yak shaving" to my taste. -- Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux |
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
|
The reason is asciidoctorj has usefull plugins that ruby asciidoctor hasn't thus if I just include the .adoc I won't have those available.
Antora is nice but feels overkill for this case. |
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
Administrator
|
It would be a lot of work, but you could run Jekyll using JRuby, then patch Jekyll AsciiDoc to use the AsciidoctorJ APIs to invoke Asciidoctor. When Ruby code is running JRuby, it can access Java objects. An alternative would be to use AsciidoctorJ to generate embedded HTML (as Abel suggested), then dump that into the source directory of the Jekyll site and let Jekyll apply a template to it. I'm curious to know what extensions are available for AsciidoctorJ that you would need to use in the site. (Unless they are very complex, they probably wouldn't be that hard to rewrite in Ruby). > Antora is nice but feels overkill for this case. I'd argue that your readme is already entirely too long and should be divided up into a documentation site to make it more approachable. So, in fact, this would be the right time to be considering Antora. Just look at the result that the AsciiDoc IntelliJ plugin was able to achieve in very short time: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/index.html That project is no bigger than yours. -Dan On Sat, Nov 21, 2020 at 2:06 AM maxandersen [via Asciidoctor :: Discussion] <[hidden email]> wrote: The reason is asciidoctorj has usefull plugins that ruby asciidoctor hasn't thus if I just include the .adoc I won't have those available. -- Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux |
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
|
Yeah - this would be too much - trying to avoid too much ;) You mean tweaking header/footer options? No they are not complex; but they are there without extra setup. i.e.https://asciidoctor.org/docs/extensions/ has a list of them - the two i'm mainly after are the copy source block combined with https://github.com/bmuschko/asciidoctorj-tabbed-code-extension which I actually ported to ruby version and contributed to asciidoctor extensions lab https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/112 but that never got merged so i would have to find a place to host that somewhere else ..which I could but I never found a good way of sharing that code easily to other jekyll users...so i'm back to try and work with asciidoctorj as here it "just works"....... That is actually why I'm looking at doing this - want to move a better way of generating and including the docs but having to maintain/write these small but useful extensions is just not something i'm keen on if I can avoid it. That rendering looks nice - definitely one of the better antora sites I've seen - but does antora help me get easier access to copy / tabbed sources or do I have to do that manually/on my own too here ? |
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
Administrator
|
> does antora
help me get easier access to copy / tabbed sources or do I have to do that manually/on my own too here I developed extensions for Couchbase that do both of these things. See https://github.com/couchbase/docs-site/blob/master/lib/tabs-block.js and https://github.com/couchbase/docs-ui-sandbox/blob/master/src/js/07-copy-to-clipboard.js. > definitely one of the better antora sites I've seen There are a plethora of Antora sites that look amazing. Many of them are listed here: https://gitlab.com/antora/antora.org/-/issues/20 > No they are not complex; but they are there without extra setup.
But they are with extra setup because what you're asking to do is to create something that doesn't exist. I think you need to rethink your rationale. And that would be to either use Jekyll AsciiDoc and rework the extension in Ruby or use Antora (and borrow extensions from the places I cited). Best Regards, -Dan |
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
|
thanks for the link of other antora sites - will definitely take a look.
my issue is that I am trying first to do this for jbang and then see how to apply it to quarkus on other sites and if I end up with having to duplicate and maintain the ruby and .js files separately it just won't happen :) with asciidoctorj there is no setup and they are simple mvn dependencies - it just don't fit well into jekyll nor antora workflows and having to go setup and maintain a set of ruby gems is fairly low on my list of things to start doing...but there might just not be a way around it ;/ |
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
Administrator
|
With AsciidoctorJ, there's no setup and they are simple mvn dependencies because someone took the time to make them available. Ruby and JavaScript have exactly the same capability, so you can get the same experience with the Jekyll and Antora workflows. It's just that someone hasn't done the work for you. I think you're making out publishing a RubyGem to be a lot harder than it actually is (especially with someone of your development experience). Frankly, it's simpler than publishing to Maven Central. -Dan On Sat, Nov 21, 2020 at 6:08 PM maxandersen [via Asciidoctor :: Discussion] <[hidden email]> wrote: thanks for the link of other antora sites - will definitely take a look. -- Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux |
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
I spent a little time setting up the readme.adoc as an Antora site: https://github.com/jbangdev/jbang/pull/535.
This includes the two bits from couchbase, the tabs-block extension and the clipboard.js. The basics of including the code so it’s usable/accessible was trivial however…. * Tabs work although they don’t look elegant, so I might have missed some important css. * The js for clipboard works but the functionality seems to rely on font awesome icons, and I can’t get it to work. is ‘far fa-copy’ a pro icon? My personal opinion is that having this readme as one page is extremely user-unfriendly. If you’re interested in pursuing Antora-izing, you should be set up with this PR to start breaking the content into reasonable sized pages. David Jencks
|
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
Administrator
|
> The js for clipboard works but the functionality seems to rely on font
awesome icons, and I can’t get it to work. is ‘far fa-copy’ a pro icon? I would just eliminate all the font stuff and just make a text link or button that says "Copy". Loading font icons is a whole other can of worms. -Dan -- Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux |
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
|
In reply to this post by David Jencks
Thank you very much David for taking the time to do that - really appreciated; but the result is what I'm trying to avoid - that inside the project is now all these parts I believe is better of in a shared component so I don't have to maintain this across multiple repos. I know Dan says one with my expertise can make that happen; but my expertise also tells me that such things gets stale fast - hence why I like asciidoctorj as here I in my circle of what I know can see they are being maintained and made reusable. For some reason (unless i'm blind) in case of ruby based asciidoctor the reusable parts gets copied around.....thats what I was trying to avoid. The whole goal of this is to get it to split up - I just didn't do that yet as I'm trying to figure out where the doc will end up living which depend on the stack used/applied. again thanks for the PR - I'll definitely take a look and see if can learn something. |
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
Administrator
|
> For some reason (unless i'm blind) in case of ruby based asciidoctor the
reusable parts gets copied around.....thats what I was trying to avoid. That's simply not true. Reusable parts in Ruby can be distributed as a RubyGem (or loaded as a RubyGem directly from git, which Bundler allows [1]). If someone's not doing that, then they're just being lazy. -Dan On Sun, Nov 22, 2020 at 2:31 AM maxandersen [via Asciidoctor :: Discussion] <[hidden email]> wrote: Thank you very much David for taking the time to do that - really appreciated; but the result is what I'm trying to avoid - that inside the project is now all these parts I believe is better of in a shared component so I don't have to maintain this across multiple repos. -- Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux |
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
Administrator
|
In reply to this post by maxandersen
> I know Dan says one with my expertise can make that happen; but my
expertise also tells me that such things gets stale fast - hence why I
like asciidoctorj as here I in my circle of what I know can see they are
being maintained and made reusable. This is just FUD. You're trying to make the claim that extensions for AsciidoctorJ get maintained whereas ones for Asciidoctor Ruby. That's just absurd. There are just as many well-maintained extensions on both sides, and the people who maintain them deserve respect for the work they do. Don't be a jerk about it. -Dan -- Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux |
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
Administrator
|
> whereas ones for Asciidoctor Ruby ...don't. But they do. I'll provide receipts: As I've explained in another thread, the asciidoctor-extensions-lab is supposed to be for *experiments*. It's not my fault people take the code out of there and pass it around without making a proper project out of it. Just because they do it that way doesn't mean there isn't a right way to do it. -Dan -- Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux |
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
|
In reply to this post by maxandersen
Thank you very much David for taking the time to do that - really appreciated; but the result is what I'm trying to avoid - that inside the project is now all these parts I believe is better of in a shared component so I don't have to maintain this across multiple repos. What are the multiple repos you mention? AFAICT everything you might be maintaining is in your one repo in my PR — not necessarily the best structure but the most compact.
Perhaps one problem is that in Antora ‘component’ has a specific meaning that I’m used to and isn’t what you mean :-) If you are saying that you would like the tabs asciidoctor extension and related Antora UI bits, and the copy-to-clipboard UI bits to be in external separately maintained reusable projects, I think that’s a good idea and I may pursue it. Publishing the tabs asciidoctor extension to npm is a trivial undertaking. However, AFAIK there is no good accepted way to make a “js + css” extension in general; for non-Antora projects you’re going to be adjusting the stylesheets and header/footer scripts yourself. My Antora UI-builder project is my idea on how this might be done, but it’s in early stages and, for instance, hasn’t been reviewed by Dan. If you know of a good technology for unified extensions to the css + js for a site, I’d like to know about it. Looking forward to your feedback, David Jencks
|
Re: have asciidoctorj output html to be include in jekyll generated site ?
|
Administrator
|
> David Jencks wrote: > If you are saying that you would like the tabs asciidoctor
extension and related Antora UI bits, and the copy-to-clipboard UI bits
to be in external separately maintained reusable projects, I think
that’s a good idea and I may pursue it. Note that the copy to clipboard feature is a planned addition to the default UI. I just haven't gotten around to merging it in yet. > However,
AFAIK there is no good accepted way to make a “js + css” extension in
general; for non-Antora projects you’re going to be adjusting the
stylesheets and header/footer scripts yourself. The extension itself should be published as a npm module (or at least set up to be loaded from git). It's still up to the UI to style it, but that's a necessary separation since tabs are part of the visual design. And the UI is already a separate software component. I don't think it's a good idea for an extension to be adding CSS other than purely utility classes. We do need a way for Antora to pick those up, perhaps by honoring docinfo. But that's a problem we should be discussing in Antora. Best Regards, -Dan -- Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux |
«
Return to Asciidoctor :: Discussion
|
1 view|%1 views
| Free forum by Nabble | Edit this page |