Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Activity
Ewan Edwards
@eskwayrd
It might not be the ideal choice size-wise. dot.js seemed promising for that, but the security warning with no patch available made me skip it.
I'll give lodash a try too. Thanks for the suggestion!
Dan Allen
@mojavelinux
I think it was this one: https://mozilla.github.io/nunjucks/
we use lodash in Antora (though I try not to use dependencies if possible)
Ewan Edwards
@eskwayrd
I've used nunjucks before, when I was building my docs with GitBook. If lodash is already used by Antora, that's one less dependency to worry about.
Dan Allen
@mojavelinux
:+1:
Josh McDonald
@sophistifunk
Quick question - are there any changes in the default generator / the shape of data going to and from each step for the new release?
Dan Allen
@mojavelinux
no, we follow semver, so the 2.0.1 release should be a no check upgrade. it only addresses bugs
the one minor exception to that is how the canonical URL is handled for pages that are missing. that probably should have gone into 2.1.0, but hindsight
2.1.0 will have some improvements, but no pipeline changes. those will either happen in a later minor or in the next major
Josh McDonald
@sophistifunk
Ack
Josh McDonald
@sophistifunk
I'm done with my research, currently creating typescript defs for the site-generator process and everything it knows about. I'm going to do them within our codebase first- then I'll ping you to review their content for accuracy, and work out where we want to put them etc before I create a PR.
Dan Allen
@mojavelinux
super!
I think the timing is good, because we really need to have a discussion about the API surface area in Antora
I think we were tentative at first because we weren't sure exactly how it would be used. but it's pretty clear now that the API will become one of Antora's best assets
Josh McDonald
@sophistifunk
I'm basing it partly on looking at sources, and partly from runtime introspection of a hacked-up site-generator script, so it's probably going to be missing some props and have some type guesses wrong, but it should be a good start at least.
Dan Allen
@mojavelinux
have you seen the architecture guides?
they are in each package
they may need some updating, but that was what we knew to be true at 1.0.0
Josh McDonald
@sophistifunk
Yeah that's one of the sources I've been using, cheers
Dan Allen
@mojavelinux
perfect
Josh McDonald
@sophistifunk
Was Antora originally written in Ruby and hand-ported to JS?
danyill
@danyill
@sophistifunk I think it was Node JS from the very start by design. I think it was a good choice FWIW as node is really gaining a following in server side and having server and client side languages the same is helpful. I am curious as to specific reasons @mojavelinux had for choosing it though
Guillaume Grossetie
@Mogztter
I think one reason is the JavaScript ecosystem (ie. libraries to build web application), another reason is probably Asciidoctor.js 🤩
Dan Allen
@mojavelinux
@danyill is correct. It was always written for Node.js (though certainly carries some of my personal style, which comes from Ruby and Java)
there are two key reasons for it being written in Node.js
  1. Node.js fits best with the web-based ecosystem, which is the primary output target
  2. Node.js is much easier to get buy-in / adoption in the enterprise than Ruby (and I say that as a person who wishes that were true for Ruby)
the resistance to Ruby has been incredibly strong (and again, I say that as a person who absolutely loves the language). Node.js is shockingly easy to get companies to adopt (for better or for worse)
but (1) is really the key reason
the alternative choice was Java, but a) I wanted more runtime flexibility (monkey patching) and b) i feared it would pin us too closely to that ecosystem (we would be a "java" tool)
and yet, Node.js still allows us to run in the JVM (one day, some how, we'll get there)
Dan Allen
@mojavelinux
we should probably put this in the history of the project somewhere, though I fear inciting a contentious discussion about it. there are valid arguments for all choices, and in the end you need to pick something
though I hope that Antora is an architecture that can be implemented again and again
I should say, thirdly, we want to try something different. there's always that "let's just go for it" aspect to a decision ;)
Josh McDonald
@sophistifunk
It's just got some rubyisms in it, is all. Was interested to know if it got switched out early, or it's just written from somebody who's spent too much time rubying ;-)
Dan Allen
@mojavelinux
B
;)
Josh McDonald
@sophistifunk
No rush to respond, because I'm knocking off for the day, but here's my typedefs: https://gist.github.com/sophistifunk/7fd33bfeca88cd297d1cdbc23dd0e24d
Dan Allen
@mojavelinux
I'll need to take a deeper look. but at first glance, I want to try to avoid coupling to Vinyl in anyway. redeclare if necessary. I'm strongly considering switch to vfile, which has the same API, or even our own impl
it should just be "VirtualFile" or "File"
Josh McDonald
@sophistifunk
I'm having a bit of difficulty wrapping my head around the difference between file.out and file.pub, they both seem to hold very similar information
Dan Allen
@mojavelinux
out is where it goes
pub is how it is referred to on the public internet
that's an important distinction (which honestly most site generators get wrong)
Josh McDonald
@sophistifunk
Cheers
I need to refine my defs for VirtualFile, then I'm going to put them into fork of Antora with a few code simplifications so I can run TSC as a JS-checker against them, in order to make sure they actually match what the code is doing. Then I'll move just the definitions and not the code changes into a new fork, so I can send in a PR
Josh McDonald
@sophistifunk
Quick question: what's the reason/difference between _contents on vinyl files and contents on catalog entries created by Antora? Is it just to work around a quirk of vinyl's getter/setters, or something more concrete / semantic?
Josh McDonald
@sophistifunk
Never mind, I've figured it out. It's just noise in my data dump
Jorge Aguilera
@jorge.aguilera_gitlab
Hi, I just tested Netlify's lambda feature and I'm very impressed how easy is to link static content with serverless code. First idea comes to mind is to have a plugin who encrypt/hide some blocks of documentation and after identify the user decrypt/show it executing some aws function
What do you think ? can be interesting ? are there some similar plugin ?
Ewan Edwards
@eskwayrd
Antora is just the HTML-generator. It doesn't provide any logic after that. You can create your own UI that incorporates additional functionality, and you can use various Javascript frameworks to do so. It's just that Antora is not involved in the operational portion, where a user is browsing your documentation. If you can make your authentication/display operations work with a hand-crafted web page, then you incorporate it into your Antora UI.