Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Activity
    David Jencks
    @djencks_gitlab
    @eskwayrd so.... do you have separate playbooks for the published site and the being-worked-on site? (or effectively different by being in different branches) With the different playbooks having different lists of sources so the published one doesn't get the "prerelease" stuff?
    Jared Morgan
    @jaredmorgs

    @mojavelinux I’m moving the discussion in the Asciidoctor gitter about the Asciidoctor version used in Antora. I know the probably reason why Antora is using the 1.x series of Asciidoctor is due to time to upgrade and test Asciidoctor 2.0 with Antora Core.

    What have you found with using it in your branch @djencks_gitlab ?

    Are there advantages to taking Asciidoctor 2.x over 1.x for Antora use?

    David Jencks
    @djencks_gitlab
    I don't know of any problems :-)
    Jared Morgan
    @jaredmorgs
    What was your motivation for taking Asciidoctor 2.0 @djencks_gitlab ? Just curiosity?
    David Jencks
    @djencks_gitlab
    I've been using it with my antora-pdf experiments because guillaume used it in asciidoctor-pdf.js
    Jared Morgan
    @jaredmorgs
    Ahh, right. Yep I could understand taking it for support with asciidoctor-pdf. Lots of good stuff happening in that project.
    David Jencks
    @djencks_gitlab
    The issue antora/antora#522 was there and I wondered why it hadn't happened months ago :-)
    antora lagging so much behind asciidoctor didn't seem like a good idea :-)
    asciidoctor-pdf.js, which is a bit of an experiment, not asciidoctor-pdf.
    Antora using asciidoctor-pdf isn't likely to happen :-)
    Martin Sarosi
    @roganjoshua_gitlab
    I hope this doesn't a bit stupid but from the CLI npm and gem names for asciidoctor-pdf collide - is there an easy way round this asciidoctor-pdf-js for example?
    Guillaume Grossetie
    @Mogztter
    are you using Windows?
    on Linux/macOS: $(npm bin)/asciidoctor-pdf should do the trick
    Matthew Setter
    @settermjd
    Is there a way of using Antora's experimental features (menu, kbd, button) with asciidoctor-pdf?
    Martin Sarosi
    @roganjoshua_gitlab
    @Mogztter I use all three but can always rename I guess
    Ewan Edwards
    @eskwayrd
    @djencks_gitlab No, I have a single playbook. The not-published aspect comes from the changes existing in unmerged branches/PRs, yet Netlify still performs preview builds so that you can review the rendered documentation with the unreleased content. I don't have to customize a playbook or modify partials/helpers to "hide" unreleased content; the content is simply unreleased. If I have many changes to make that comprise unreleased content, I make a branch specifically for that version, and create PRs for that branch. Once all of the prerelease work is approved and merged into the unreleased version branch, I can merge that branch into master to publish all of the changes in one operation.
    David Jencks
    @djencks_gitlab
    @eskwayrd Do you have your playbook in the same repo as the site content? How does the playbook know what unreleased-content branches to include?
    And, thanks for the explanation!
    Toby Deitrich
    @ctdeitrich
    Can anyone give me guidance on how to link to an ordered list item by number? In other words, I want to utilize the functionality described in asciidoctor/asciidoctor#1246.
    So if I have an ordered list, I want to link to the anchor have it spit out the item number.
    It looks like this Asciidoctor PR would do it:
    asciidoctor/asciidoctor#2813
    And this got merged in July 2018
    I am using Antora 2.2.0 but I do not see it working the way it's described in issue 1246 above.
    David Jencks
    @djencks_gitlab
    Which version of asciidoctor.js is that fix in?
    Also, I don't fully understand the discussion, but my impression is that you can put [[link2.2.2]] in your list and link to it but the text in the link may not be automatically the list number.
    Toby Deitrich
    @ctdeitrich
    Here's my test code:
    .Test List
    
    . Ordered Item 1
    . [[item2]] Ordered Item 2
    . Ordered Item 3
    
    Refer to step number <<item2>> above.
    What I want is for that last line, in the HTML, to read "Refer to step number 2 above."
    What I get instead is:
    Screen Shot 2020-01-22 at 11.18.36 AM.png
    The value to what I'm looking for is, if a new step is added ahead of [[item2]], then the last line will then render to "Refer to step number 3 above."
    I dont know how to determine which version of asciidoctor.js the fix is in. Can I determine that from the PR? asciidoctor/asciidoctor#2813
    David Jencks
    @djencks_gitlab

    Looking at the test for #2813, it has

    . Ordered list, item 1, without anchor
     . [[step-2,Step 2]]Ordered list, item 2, with anchor

    so I think perhaps you are currently responsible for setting the text you want to show up, and updating it when the list changes.

    I don't know how to figure out the asciidoctor.js version either :-)
    If asciidoctor.js includes the asciidoctor changelog that might help.
    Toby Deitrich
    @ctdeitrich
    Bummer. Maintaining the text would be reasonable for short lists... but for long lists, It's much harder. ("Is this now step 33, or 34? Let me count the dots...")
    David Jencks
    @djencks_gitlab
    yes.
    Is there a chance the list number is available as an attribute?
    Toby Deitrich
    @ctdeitrich
    I don't follow the question... say more?
    David Jencks
    @djencks_gitlab
    well, asciidoctor has to compute the list number in order to render it. Perhaps it makes it available as an attribute, so you could refer to it in the [[]]
    [[my-step,{step-number}]]
    I'm not even sure how to investigate that!
    Toby Deitrich
    @ctdeitrich

    good idea! but doesn't work :(

    .Test List
    
    . Ordered Item 1
    . [[item2, {step-number}]] Ordered Item 2
    . Ordered Item 3
    
    Refer to step number <<item2>> above.

    asciidoctor: WARNING: skipping reference to missing attribute: step-number

    Doesn't work either asciidoctor: WARNING: skipping reference to missing attribute: listindex
    David Jencks
    @djencks_gitlab
    I totally made up step-number, it would be amazing if it did work!
    Toby Deitrich
    @ctdeitrich
    I think what I'm after isn't implemented, see https://github.com/asciidoctor/asciidoctor/issues/1246#issuecomment-505587078 leading to open issue asciidoctor/asciidoctor#3253
    David Jencks
    @djencks_gitlab
    Is the list item number constructed by css? the last #1246 comment is Fair enough. But I never claimed that was the goal since the list number is simply not a referencable label. HTML does not make that information available and thus we can't use it. And we're not going to start tracking list numbers ourselves (at least, not right now) since that would lead to all sorts of other complications.
    Ewan Edwards
    @eskwayrd
    @djencks_gitlab Yes, my playbook exists within my content repo. I don't often include new components, but when I do, I simply update the playbook to include the new content. Since the playbook change is in a PR, the preview build showing the new content is not published to the main site. When the PR is merged to master, the new content is published.
    Coordinating components in multiple repos is notably more challenging. AFAIK, there is no mechanism for a PR in one repo to trigger a build in another repo. That was the primary reason that I elected to place my playbook, my content, and my theme in a single repo. I can make commits that affect all three concerns at once, and the build context is notably simpler.
    Managing multi-repo publishing is certainly possible, but choosing one repo avoids additional tooling to make that happen. When you don't have enough time to keep up with content priorities, those are the kinds of choices that get made. :smile:
    David Jencks
    @djencks_gitlab
    That makes sense.... I rather wish there was a page somewhere talking about the tradeoffs between different ways of organizing repos. I appreciate some logical and separation of concerns advantages of having 3 sets of repos (content, playbook, and UI) but it definitely makes a lot of things much harder to manage.
    David Jencks
    @djencks_gitlab
    @settermjd IIUC you are using asciidoctor-pdf.js to make pdfs for your antora site? Would you be interested in trying my adaptation of that to run in antora? https://github.com/djencks/asciidoctor-pdf.js/tree/antora It's not the easiest thing to set up, unfortunately. Is your project repo public? If so I could experiment with it.
    Pi3r
    @PierreR
    Out of curiosity, is the list of showcase sites (antora/antora.org#20) displayed somewhere on the web site (https://antora.org/) or within the docs ?
    Chris Cranford
    @Naros
    Is there a way with Antora to enforce including the _attributes.adoc file without having to use the include macro in each .adoc?