The official chat room for Antora is now located at https://antora.zulipchat.com. Please join us there!
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.
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
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
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.jssidesteps 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.
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!
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)
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
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.
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.
@KLynn2019 do you mean separate component? What have you tried that doesn't work?
My suspicion is that you will either need to hardcode the link or use some new features in 2.3.0 which I'm not even sure are merged into master yet. Dan has been adding some ways for the UI to use the content catalog. I think you'd need to call a method on the content catalog to get the location of your linked page from antora coordinates. However, I'm not at all sure about this.
@Tschakki If your Swagger HTML is built separately from Antora, you can copy it into the path where Antora generates its HTML (specified in the playbook as the
dir field under output). Then, all you'd need to do is add a link in your UI to that page, doing something like <a href="{{uiRootPath}}/../path/to/swagger.html">Swagger</a>. Specifically, if your Antora-generated HTML is in a folder called build, and you place swagger.html at the root of build, then that link would be <a href="{{uiRootPath}}/../swagger.html">Swagger</a>.
Yes. If you want API pages decorated like any other pages, I'd suggest converting the Swagger-collected API details into Asciidoc markup, and then those generated pages are just like any other page that you author. See: https://phauer.com/2017/rest-api-documentation-swagger-asciidoc/
@KLynn2019 I would try figuring out where the attachments will end up in your generated site and defining your own property, globally, pointing to it. e.g.
commonAttachmentsDir: /shared/1.0/attachments and link:{commonAttachmentsDir}/foo/bar/my.pdf I have no idea if this will actually work though...
The interactive part of Swagger was relatively easy to separate from the presentation part of Swagger, since the latter could be used server-side and the former runs in the browser. If you translate to Asciidoc format, you can still use the interactive bits, but you have to do a bit of work to make that happen.
https://swagger.io/docs/specification/about/
Looks like the Swagger spec became the OpenAPI spec, and that Swagger is now "just" one tool that uses it instead of the only tool. When I last used Swagger, it was before OpenAPI existed (nearly 5 years ago).
Looks like the Swagger spec became the OpenAPI spec, and that Swagger is now "just" one tool that uses it instead of the only tool. When I last used Swagger, it was before OpenAPI existed (nearly 5 years ago).
@djencks_gitlab Yes, I mean separate component. I have one that contains content that's used by multiple sites. That's where I'd like to store the PDFs.
Per the Antora documentation, I didn't specify an explicit attributes location. I just used
Originally I tried specifying the component and module:
When that didn't work, I tried specifying a different module in the app-specific component:
When THAT didn't work, I went ahead and put the PDF in an attributes folder in the module with the link:
In all cases, Antora created an _attributes folder with the PDF in it, but in no case did clicking on a link display a PDF. In the latter case (attribute in same module as link), I got a "file not found" message even though I could see the PDF in the correct folder.
Per the Antora documentation, I didn't specify an explicit attributes location. I just used
{attributesdir}.Originally I tried specifying the component and module:
link:Shared:Settings:{attributesdir}/Setting.pdf[link text]When that didn't work, I tried specifying a different module in the app-specific component:
link:Settings:{attributesdir}/Setting.pdf[link text]When THAT didn't work, I went ahead and put the PDF in an attributes folder in the module with the link:
link:{attributesdir}/Setting.pdf[link text]In all cases, Antora created an _attributes folder with the PDF in it, but in no case did clicking on a link display a PDF. In the latter case (attribute in same module as link), I got a "file not found" message even though I could see the PDF in the correct folder.
@KLynn2019 The
link macro doesn't understand Antora's component ids as used in the xref macro. I think that this is the relevant issue: antora/antora#180
One suggestion, which is a hack to be sure, would be to place all of the PDFs in one module, and then in other modules, create a symbolic link to the PDFs in the first module, making specific PDFs available to the current module without incurring additional file storage. If your authoring/publishing infrastructure is all on Posix-compatible file systems (ie, not on Windows) this could work well. If you're on Windows, your mileage may vary. :-)
@eskwayrd Your latter suggestion is probably what's going to happen except they will be on our docs server. I was just trying to sidestep that so that the writing team would have more control over where that content exists (again, ideally in a component accessed via Antora).
We are a Windows shop...for better or worse. :) It's not clear to me where the symlink would be created or how it would be used by the writers who will be taking over this data once I finish with it.
We are a Windows shop...for better or worse. :) It's not clear to me where the symlink would be created or how it would be used by the writers who will be taking over this data once I finish with it.
@KLynn2019 Fair comments.
There can be undesirable side effects of using symlinks, especially with varying support across platforms.
While I understand the desire for authors to have one way to manage things, PDFs tend to be an exception for a text-based file workflow. Since they tend to be notable larger than the Asciidoc files around them, and because they are an opaque format that is hard for versioning systems, like Git, to reason about, adding them to your repos, especially if you have large numbers of PDFs, tends to be an idea that you outgrow fairly quickly.
The solution tends to be whatever works for your team's skillset, your budget, and operational capabilities. For example, some teams that I've worked with serve all of their regularly updating, large binary assets in a shared Dropbox folder, and their web pages simply link to those.
There can be undesirable side effects of using symlinks, especially with varying support across platforms.
While I understand the desire for authors to have one way to manage things, PDFs tend to be an exception for a text-based file workflow. Since they tend to be notable larger than the Asciidoc files around them, and because they are an opaque format that is hard for versioning systems, like Git, to reason about, adding them to your repos, especially if you have large numbers of PDFs, tends to be an idea that you outgrow fairly quickly.
The solution tends to be whatever works for your team's skillset, your budget, and operational capabilities. For example, some teams that I've worked with serve all of their regularly updating, large binary assets in a shared Dropbox folder, and their web pages simply link to those.
@eskwayrd Thank you for your perspective. Much appreciated!
The PDFs range from 35-60K in size but compared to the Asciidoc files, they are quite large, and in certain sites there would be a lot of them. I will see if I can get the site admin to put these into a single location so that at least they're easy for writers to reference from within the Asciidoc files.
The PDFs range from 35-60K in size but compared to the Asciidoc files, they are quite large, and in certain sites there would be a lot of them. I will see if I can get the site admin to put these into a single location so that at least they're easy for writers to reference from within the Asciidoc files.
@djencks_gitlab @gmarpons I’ve got the basic system working again after realising I wasn’t supporting the correct build branch in my site.yml. I’m going to record a demo of the solution at the current state, before I begin messing with the global version variables that @gmarpons suggested.
I’ll share it here for reference once it’s upload to youtube
due to the distributed nature it's obviously not very straight-forward
we're also thinking about possible solutions, but have not dived in very deep yet
a naive approach would be to have specialized
site-pr.ymlfiles within the master documentation build project, but the bigger issue is, that PRs usually would be triggered from "downstream" projects where the actual content lies, potentially even from multiple ones.
so, in the end it also depends to some extend on the used infrastructure (e.g. Jenkins) and whether it is possible to define such relations and trigger respective build actions
@djencks_gitlab I hardcoded the link in the top nav now. :) Changes are now live: https://lisk.io/documentation/lisk-core/api.html
thanks again for the help :)
@gmarpons I didn’t consider that perhaps the reason why the solution you proposed isn’t working for me is because of a version incompatibility. We are currently still running Antora 2.0
@jaredmorgs Yes, I think you need at least version 2.1. The functionality added in this issue is relevant to my experiment: antora/antora#430.
