have asciidoctorj output html to be include in jekyll generated site ?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

have asciidoctorj output html to be include in jekyll generated site ?

maxandersen
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 ? :)
Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

abelsromero
maxandersen wrote
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.
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.
Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

mojavelinux
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:
maxandersen wrote
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.
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.


If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/have-asciidoctorj-output-html-to-be-include-in-jekyll-generated-site-tp8353p8354.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

maxandersen
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.
Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

mojavelinux
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.

Antora is nice but feels overkill for this case.


If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/have-asciidoctorj-output-html-to-be-include-in-jekyll-generated-site-tp8353p8356.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

maxandersen
mojavelinux wrote
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.
Yeah - this would be too much - trying to avoid too much ;)

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.
You mean tweaking header/footer options?

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).
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".......

> 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.
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.

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.
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 ?
Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

mojavelinux
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


> 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
Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

maxandersen
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 ;/

Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

mojavelinux
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.

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 ;/




If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/have-asciidoctorj-output-html-to-be-include-in-jekyll-generated-site-tp8353p8360.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

David Jencks
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

On Nov 21, 2020, at 5:21 PM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

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] <<a href="x-msg://40/user/SendEmail.jtp?type=node&amp;node=8361&amp;i=0" target="_top" rel="nofollow" link="external" class="">[hidden email]> wrote:
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 ;/




If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/have-asciidoctorj-output-html-to-be-include-in-jekyll-generated-site-tp8353p8360.html
To start a new topic under Asciidoctor :: Discussion, email <a href="x-msg://40/user/SendEmail.jtp?type=node&amp;node=8361&amp;i=1" target="_top" rel="nofollow" link="external" class="">[hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux



If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/have-asciidoctorj-output-html-to-be-include-in-jekyll-generated-site-tp8353p8361.html
To start a new topic under Asciidoctor :: Discussion, [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

mojavelinux
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
Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

maxandersen
In reply to this post by David Jencks
David Jencks wrote
I spent a little time setting up the readme.adoc as an Antora site: https://github.com/jbangdev/jbang/pull/535 <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?
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.

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.
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.
Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

mojavelinux
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:
David Jencks wrote
I spent a little time setting up the readme.adoc as an Antora site: https://github.com/jbangdev/jbang/pull/535 <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?
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.

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.
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.


If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/have-asciidoctorj-output-html-to-be-include-in-jekyll-generated-site-tp8353p8364.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

mojavelinux
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
Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

mojavelinux
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
Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

David Jencks
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. 

I completely don’t understand what you mean here, what specifically are these parts that you think should be in a shared component?
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

On Nov 22, 2020, at 1:31 AM, maxandersen [via Asciidoctor :: Discussion] <[hidden email]> wrote:

David Jencks wrote
I spent a little time setting up the readme.adoc as an Antora site: https://github.com/jbangdev/jbang/pull/535 <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?
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.

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.
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.


If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/have-asciidoctorj-output-html-to-be-include-in-jekyll-generated-site-tp8353p8364.html
To start a new topic under Asciidoctor :: Discussion, [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Reply | Threaded
Open this post in threaded view
|

Re: have asciidoctorj output html to be include in jekyll generated site ?

mojavelinux
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