antora/users

The official chat room for Antora is now located at https://antora.zulipchat.com. Please join us there!

Dan Allen

@mojavelinux

It’s just the general question how to add an additional page to Antora UI that is NOT based on .adoc

It's possible to add a completely static page with no templating using the static_files field of ui.yml. However, I'd like to see a way to add a page that does use templating without having to have a corresponding .adoc file. It will require some thinking, but it's something we could achieve.

Hey, quick update: The way @djencks_gitlab described it works :) I Added an empty .adoc file with just title and :page-layout: swagger and as I added this layout to UI before, it immediately worked

Indeed, this is the way to do it today.

Is it possible to point to attachments that are stored in an attachments folder that's not in the same module where the link is being created?

Not yet. That's an open feature request.

Is there a way to setup CI to build PR branches automatically for viewing?

Netlify supports this out of the box. Couchbase has it enabled https://github.com/couchbase/docs-ui/blob/master/netlify.toml (though that example is for the UI, but it's the same thing)

Dan Allen

@mojavelinux

I haven't used component attributes so far.

It's new in Antora 2.3 (alpha). They are scoped to the component version, though in the UI model the attributes from the latest component version get hoisted to the attributes for the component overall.

So ideally I'd prefer to have a way to define the attributes in such a way where the components are in repo A but without having to explciitly include a file in each asciidoc page.

that's exactly what has been implemented in 2.3.0 (alpha)

here's an example:

name: mq-connector
title: MQ Connector
version: '3.x'
nav:
- modules/ROOT/nav.adoc
asciidoc:
  attributes:
    page-component-desc: Connect to Anypoint MQ, MuleSoft's multi-tenant cloud messaging service for the enterprise.
    page-connector-type: Connector
    page-exchange-url: https://www.anypoint.mulesoft.com/exchange/com.mulesoft.connectors/anypoint-mq-connector/
    page-vendor-slug: msmq
    page-vendor-title: MuleSoft

we're looking for feedback on this feature.

the pages in the component version automatically inherit these attributes.

they are also accessible from the UI model via:

page.componentVersion.asciidocConfig.attributes.page-component-desc

site.components.name-of-component.latest.asciidocConfig.attributes.page-component-desc

though I'm likely going to change "asciidocConfig" to just "asciidoc" for consistency.

https://github.com/mulesoft/docs-site-ui/pull/10/files#diff-f86fcd0a159ed3c6c9016a041fead42cR53-R79

Dan Allen

@mojavelinux

I'd better like to listen to @mojavelinux 's opinion first, because maybe we devise something we can add to Antora to facilitate global navigation trees.

Could you clarify what that was about? Don't hesitate to open an issue. Even if we decide to close it in favor of something else, it is captured.

Chris Cranford

@Naros

@mojavelinux thanks for the insight; I'll take a peak at Antora 2.3 and see if we can make use of that immediately after the holidays. That's so awesome you guys already had this coming!

Dan Allen

@mojavelinux

:+1:

trying our best to stay a step ahead ;)

Pi3r

@PierreR

Hi
How is the right side menu generated for instance here: https://lisk.io/documentation/lisk-sdk/lisk-commander/user-guide.html
Is this a new feature that requires a recent version of antora ?

This doc website is awesome by the way.

Chris Cranford

@Naros

I have not looked at the new UI aspects @PierreR, but you can accomplish that even with older releases. What we did at https://debezium.io/documentation/reference/1.0/ was basically add some custom CSS styles that repositions the toc on the right side.

As an example: https://debezium.io/documentation/reference/1.0/connectors/postgresql.html

We simply use the default-ui with some supplemental overrides and additional css definitions.

I haven't yet looked at the 2.3 change log, but if that's coming, that'll be a nice addition as well.

Dan Allen

@mojavelinux

@PierreR if it's like the open MR in Antora, it's jut done using JavaScript. It reads the headings on the page and populates the sidebar.

Both Couchbase and MuleSoft do it too. It's very little code. See https://github.com/couchbase/docs-ui/blob/master/src/js/02-on-this-page.js Once 2.3 is out, I'll get that merged into the UI

Dan Allen

@mojavelinux

@Naros I don't see debezium on the showcase issue yet. feel free to add it here: antora/antora.org#20

Chris Cranford

@Naros

@mojavelinux I'll mention it to Gunnar when we're all back from the holiday break and if he's fine with it, I'll add it.

Dan Allen

@mojavelinux

:+1:

in 2020, we will get that website up so that you'll be in the gallery.

good way to promote both projects ;)

Chris Cranford

@Naros

Hopefully soon I can get to adding a bit more color to our documentation so that its less white/black/grey :)

Dan Allen

@mojavelinux

I could say the same about the Antora docs

danyill

@danyill

Just updated some of the sites on the showcase. Hey this openZeppelin site is really sweet

Dan Allen

@mojavelinux

that IS really nice

looks like the adopted the version selector from MuleSoft. https://docs.openzeppelin.com/sdk/2.6/

;)

word must get around in Buenos Aires

there are a few more things still to wrap up for 2.3, but we're well on our way to having it out. I may slightly change how the built-in resolvePage helper works to return a page model instead of a file. and I'm hoping to get supplemental worktrees in too, though there are some open questions about it still to address.

from there, we'll be looking towards 3.0

danyill

@danyill

I opened an issue about editor tooling for Antora. It'd be good to see some thoughts on what people would like to see. antora/antora#540

Dan Allen

@mojavelinux

I agree. And that's a fine place for it as an architecture / requirements discussion.

Josef

@tbugfinder

Hi, I'm wondering if there's a repo with different antora UI styles available?

danyill

@danyill

@tbugfinder not as such but there's quite a few open source UIs listed here antora/antora.org#20

Mark

@scitechcs

Having a right-side on-page table of contents is a nice feature for longer topics. There are a couple of considerations: (1) Use a script and CSS combination that highlights the section you are viewing, (2) Add a script that creates a vertical scroll offset when you click one of the on-page TOC links. With the script I use, clicking one of these links leaves the target heading hidden behind the top banner and you have to scroll down for the heading to appear. A second script is needed to create a vertical scroll offset so the heading is visible after clicking the link.

Mark

@scitechcs

I posted a screenshot of my Antora implementation (with product names blurred out) so you can see the on-page navigation. The on-page navigation highlight doesn't exactly match the section being viewed because of the javascript scroll offset, but it's close.

Josef

@tbugfinder

Hi @scitechcs, which search option did you integrate?

Dan Allen

@mojavelinux

@scitechcs what you are showing (which looks good) is what will be added to the default UI. I just haven't had time to review and merge it yet. I'll do it shortly after the 2.3 release is ready.

Mark

@scitechcs

I used the JavaScript version of the Zoom search engine. My site is installed as a help system along with software on a local computer, so I have to use a client side search engine. I think it's a good search engine. I like the Google style results page that uses the description attribute from the asciidoc pages.

It will be great to have the on-page navigation included by default.

Dan Allen

@mojavelinux

@scitechcs totally agree

David Jencks

@djencks_gitlab

I'm wondering if there's a way or conceptual model to have a site (or component) with individually versioned pages. I'm thinking of something like Guillaume's "blog antora" https://github.com/yuzutech/blog.yuzutech.fr except where you can go to old versions of each post. Perhaps one starting point would be to spread out the git versions of a page into separate content catalog entries, or even to preprocess the git repo to duplicate page versions into separate files.

Where communities thrive

People

Repo info

Activity