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
    @styx_hcr_twitter Indeed you can include content from any component in any other component. There's an example at multiple-components/shared-content-xrefs in my simple-examples project.
    Ewan Edwards
    @eskwayrd
    @jcayouette I use Netlify to build+host my docs. They make it dead simple to have PR-specific builds of my docs, triggering on each commit. In the past, I've used Travis CI, Circle CI, buddybuild, Jenkins. All of those take some effort, from sorta simple to sometime extreme effort. Netlify takes a few clicks. You're rolling in under a minute, and it just works.
    The only gotcha is that they optimize for pulling master (or the specified branch) only. If your Antora setup is a "local" repo that involves multiple branches for doc content, you need to run a script that performs a full clone.
    Jared Morgan
    @jaredmorgs
    @gmarpons thanks for confirming. I’ll have to insist we upgrade Antora to 2.2 sooner rather than later.
    Ewan Edwards
    @eskwayrd
    @jaredmorgs It should be a drop-in replacement. One thing that you can do to make sure that it's the same is to compare the output before and after the upgrade, say using diff. You should only see differences in the "generator" meta tags for the HTML files (the sitemaps will have new timestamps).
    Chris Cranford
    @Naros
    Hi guys, hopefully a quick question. Generally we've be placing our asciidoc variables/attributes in _attributes.adoc, but is there a way to instruct Antora to globally include that file or its contents as a part of building each page without explicitly doing so in the various .adoc files themselves?
    Ewan Edwards
    @eskwayrd
    You can define global attributes in your playbook file:
    asciidoc:
      attributes:
        foo: bar
    David Jencks
    @djencks_gitlab
    Or, now, in an antora.yml file.
    Ewan Edwards
    @eskwayrd
    Are attributes defined in component descriptor files global, or only used for that component?
    David Jencks
    @djencks_gitlab
    just in that component
    Ewan Edwards
    @eskwayrd
    Thanks! I haven't used component attributes so far.
    David Jencks
    @djencks_gitlab
    I've only read about them :-)
    To answer Chris's actual question, there is no way to auto-include an .adoc file in all others, and the format is a bit different... so the playbook and descriptor solution produces the desired effect using a different syntax.
    Chris Cranford
    @Naros
    Sorry @eskwayrd I totally missed your comments earlier, my apologies.
    For now I've swapped to using the global attributes in the playbook file, but I don't paritcularly care for that style because our documentation is hosted in repo A while the playbook is maintained in repo B where our web content is built.
    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.
    As for component attributes, that might work but I'm not aware of how to use those. @djencks_gitlab do you have a reference I can review on how to use them?
    I guess if I understand correctly component descriptor would be the antora.yml file.
    I assume it follows the same style as what Ewan showed earlier for the playbook?
    Dan Allen
    @mojavelinux
    It took me a while to get back into the swing of things after my 4,000 mile journey, but I'm happy to report that I made it back safe and that 2.3.0-alpha.2 is now available. :tada:

    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.

    Dan Allen
    @mojavelinux

    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)

    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.
    Dan Allen
    @mojavelinux

    they are also accessible from the UI model via:

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

    or

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

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

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