Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Activity
    Mona Bärenfänger
    @Tschakki
    @Janaka-Steph no, not really. I want to include a new page API in the top nav of the Antora default UI, and this shall lead to a page with swagger-ui. As explained above this is not included in an .adoc file. It shall be a new page that is part of the Antora-UI. I basically try to include swagger in Antora UI
    But the main problem is the routing of Antora UI, it is not clear to me once I created the .hbs snippet, how can I display the content and link to it from the UI
    I have a hacky way of doing it in the Antora UI preview if I run gulp preview but if I bundle it, it does not work with antora, so I think I am missing something here
    David Jencks
    @djencks_gitlab
    Normally .hbs files are either a whole layout or part of a layout, but it sounds like you have a whole page?
    Mona Bärenfänger
    @Tschakki
    @djencks_gitlab I created both as I am a little lost, and then I check for layout inside article.hbsand then display the swagger-ui in case layout=swagger - but this is probably not the best way to do it (and only working in preview) https://github.com/LiskHQ/lisk-docs/blob/antora/src/partials/article.hbs
    David Jencks
    @djencks_gitlab
    You can add content using supplemental-ui in the playbook project; the antora docs do this to swap out some .hbs files and add robots.txt. But now it sounds like you want this page to use a layout?
    I'm confused about your goals :-)
    Mona Bärenfänger
    @Tschakki
    I really try to explain it simple ^^ I just want to adda page that is not related to any .adoc file to my Antora UI. Just a normal HTML page. And I want to link to it from top nav
    David Jencks
    @djencks_gitlab
    hmmm... Normally the UI doesn't have any pages in it. It has layouts to apply to embeddable html. You can add static files (such as robots.txt) but there's no obvious way to link to them in a nav.adoc.
    Mona Bärenfänger
    @Tschakki
    hmmmm that’s bad if true :(
    David Jencks
    @djencks_gitlab
    Is there one of these swagger-ui pages or lots, one per something else?
    Mona Bärenfänger
    @Tschakki
    Something simple like this should be straightforward imho
    David Jencks
    @djencks_gitlab
    Adding a page to a UI would mean it shows up in every site you used the UI for. Is that what you want?
    Mona Bärenfänger
    @Tschakki
    One page for now, but can be more in future
    David Jencks
    @djencks_gitlab
    Or do you want this page or pages to show up in one particular site?
    Mona Bärenfänger
    @Tschakki
    I don’t need it to show up in the nav generated by nav.adoc, I want to have it in the top nav, aka header of the antora UI
    David Jencks
    @djencks_gitlab
    ok.... do you want it to have a similar layout to other pages in your site?
    Mona Bärenfänger
    @Tschakki
    nope, it has it’s own layout
    David Jencks
    @djencks_gitlab
    I'm not familiar with swagger, especially in js. Does that take some information from https://testnet.lisk.io/api/spec and transform and display it dynamically?
    Or is that a code generator that works when you build the site?
    So when viewing the site no reference to https://testnet.lisk.io/api/spec occurs?
    Mona Bärenfänger
    @Tschakki

    Yes, it transforms the content of https://testnet.lisk.io/api/spec dynamically. As I mentioned, this works perfect if I run gulp preview.

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

    David Jencks
    @djencks_gitlab
    Perhaps I'm nitpicking, but Antora doesn't have pages, your site does. And normally the UI doesn't have pages either, it has layouts.
    Mona Bärenfänger
    @Tschakki
    Hmmm maybe we get closer? Is there any documentation about the concept of these layouts? That might help me
    David Jencks
    @djencks_gitlab
    Most of the docs I've found about layouts is at the handlebars site. However, if it works in preview but not when you generate your site that suggests that your modifications aren't getting into the UI bundle you are using to generate your site, which is an easier problem :-)
    Mona Bärenfänger
    @Tschakki
    Oh no, I think they get into the UI bundle. But The thing is it fails ^^
    David Jencks
    @djencks_gitlab
    Have you checked "by hand" that your changes are actually in the UI bundle Antora is actually using?
    Mona Bärenfänger
    @Tschakki
    Error: default layout not foundis the error
    I will look at the handlebar docs and see if they can help me...
    thanks for your help so far!
    David Jencks
    @djencks_gitlab
    they won't help, you've broken something else....
    did you set the default layout in the playbook or is it still "default"?
    Mona Bärenfänger
    @Tschakki
    as I said I did it the hacky way. I truely believe there is a more simple way, I just don’t know it, and sadly it’s not documented for Antora UI
    I did not set the default layout in playbook, so it should be default
    David Jencks
    @djencks_gitlab
    Is the gitlab URL you showed your actual UI you are using?
    Mona Bärenfänger
    @Tschakki
    Github you mean? Then yes :)
    This is branch with site.yml: https://github.com/LiskHQ/lisk-docs/blob/build/site.yml
    This is the UI: https://github.com/LiskHQ/lisk-docs/tree/antora
    David Jencks
    @djencks_gitlab
    I don't see anything wrong yet, but the error you get suggests that the UI bundle that Antora is trying to use has major problems, and that that default layout .hbs is not in the expected location. I would compare your built UI bundle with a downloaded Antora default UI bundle and check that everything seems to be in the right place.
    Mona Bärenfänger
    @Tschakki
    Ok thanks, I will double check :)
    This is btw the commit where I tried to included swagger-ui: LiskHQ/lisk-docs@44e1e65
    You can see there I needed to edit the file build-preview-pages.js to make it work. My guess is that a different file is used during the build and this is why it fails
    David Jencks
    @djencks_gitlab

    I think you have two problems:

    • your UI is broken somehow so that not even the default layout is found by Antora
    • I think there's also a conceptual problem in that layouts are only used to "decorate" or lay out actual pages generated by Antora. I don't think you will be able to end up with a page using the swagger layout unless that page is known to Antora. Your change to build-preview-pages.js sidesteps this.

    Normally you specify the layout as a page attribute :page-layout: swagger I think you can have a page with just a top level title and that attribute. I would suggest also including the URL used by your js code as a page attribute :page-swagger-url: https://testnet.lisk.io/api/spec, you can reference it in the .hbs with {{page.attributes.swagger-url}}

    You could also consider writing an asciidoctor extension to generate the page statically at build time, so the site doesn't need to access that URL.

    Mona Bärenfänger
    @Tschakki
    Thank you @djencks_gitlab ! This was really useful help :) I will follow your suggestions and try it this way :+1:
    David Jencks
    @djencks_gitlab
    If, as I think, your page needs to be generated by Antora, your link to it in the header might be tricky (I'm not sure at all). The version of Antora under development (2.3.0) has some enhancements to make more information available to the UI. Ideally you'd use an xref in the header to link to your page, and that might only work with the development version. I'm just not sure.
    Including external content in an Antora site is a big open topic, for instance java based projects usually would like javadoc. It's very tricky to do right which is why there isn't good support yet.
    good luck and let us know what happens!
    Mona Bärenfänger
    @Tschakki
    :+1:
    Mona Bärenfänger
    @Tschakki
    I agree it is useful and needed to have some parts of the docs auto generated with e.g. JavaDoc from the code. We plan to do this as well with TypeDoc (we want to use it for documenting the technical reference of certain parts of the software) Also API documentation is better auto-generated, this is why we use swagger (where you can explore the API interactively through the UI additionally)
    Mona Bärenfänger
    @Tschakki
    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: https://liskhq.github.io/lisk-docs/lisk-core/api.html#/Accounts/getAccounts :D
    KLynn2019
    @KLynn2019
    Hi all...quick question: 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? Antora documentation and my tests up to this point suggest no but maybe I'm misreading/doing it wrong.
    What I'd like to do: Store PDFs as attachments in the same repository that contains other shared content. Multiple sites access these files so it would be nice to have them all in one location.
    What I'm trying not to do: Have individual PDFs in a separate standalone location on our docs server. It's not the end of the world, but it would be one more thing for the site admin (who's not on the writing team) to worry about.
    David Jencks
    @djencks_gitlab
    @Tschakki excellent! However, for me the links in the header don't work, do they for you?