Community support for Antora, the static site generator for making documentation sites based on AsciiDoc.
@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?
@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?
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 :-)
on Linux/macOS:
$(npm bin)/asciidoctor-pdf should do the trick
@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.
And, thanks for the explanation!
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.
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.
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.
What I want is for that last line, in the HTML, to read "Refer to step number 2 above."
What I get instead is:
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
Looking at the test for #2813, it has
. Ordered list, item 1, without anchor
. [[step-2,Step 2]]Ordered list, item 2, with anchorso 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.
Is there a chance the list number is available as an attribute?
[[my-step,{step-number}]]
I'm not even sure how to investigate that!
will try with
listindex per https://www.methods.co.nz/asciidoc/chunked/ch17.html
Doesn't work either
asciidoctor: WARNING: skipping reference to missing attribute: listindex
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
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.
@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:
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.
@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.
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 ?
