How to do Antora crossreferences between docs repos?

Quite often there is a need to refer to some content from another docs repository
(so, another Antora component in our setup).
Up until very recently, I have done it by using an url:

https://docs.fedoraproject.org/en-US/package-maintainers/Package_Maintenance_Guide[Package Maintenance Guide]

Now I have discovered that Antora also supports another method:

xref:package-maintainers::Package_Maintenance_Guide.adoc[Package Maintenance Guide]

My question is, which one should be preferred?

There are some cases, like referencing partials, that can only be done with the xref method.
And also it is not dependent on the domain name, so it will work e.g. in staging.

But, unlike the link method, the result cannot be previewed with a simple local ./build.sh && ./preview.sh.
Instead, changes have to be commited and pushed into a branch in a fork,
then docs-fp-o checked out, site.yml modified accordingly, built.
Only the a preview is possible to see if the link actually works.
That is so cumbersome that in the name of productivity, I am still leaning towards just using urls.
Do you have any thoughts on this topic?

1 Like

I’d prefer the xref method, as it’s more robust if a URL changes (and also doesn’t take the reader away from a translated page). The preview issue is annoying, but I personally rather deal with that and have the page “future proofed”. Once you’ve done a few xrefs you start getting pretty comfortable with getting them right on the first try. :slight_smile:

If you are only working with a few others docs repo, you can add these to your own site.yml instead :

content:
  sources:
  - url: .
    branches: HEAD
  - url: https://pagure.io/fedora-docs/package-maintainer-docs.git
    branches: main

It will be way faster than building the whole docs-fp-o, and still allow you to preview your local changes without needing to push anything.

4 Likes

Today I learned! That makes total sense, but I never thought of doing that. Thanks, @darknao!

1 Like

Thank you for the responses!

I did not realize that the two options are different in the published site too, through translations.
That is a good reason to prefer xref.

The local site.yml change looks really useful.
I will take that into use.
I had already tried to avoid the push by using file:// urls in my docs-fp-o method, but that did not work.
Nice to see that filesystem paths do work.
I also did not realize that HEAD works as the branch specifier —
it seems obvious now, but it was not for me :slight_smile:

This is such a good tip that if I will add it to Fedora Documentation Team :: Fedora Docs when I have some time.

2 Likes

+1. I think this is the best practice to follow whenever possible. Some time back, I wrote a guide on the Fedora Docs docs documenting the three ways to write xref’s in Fedora Docs already, but perhaps it could be made more visible:

https://docs.fedoraproject.org/en-US/fedora-docs/asciidoc-fedora/markup/#snippets

I also learned something new, this is amazing! It would be so nice to see this snippet added into the Building a local preview page in the Fedora Docs contributing guide for writers:

https://docs.fedoraproject.org/en-US/fedora-docs/contributing/local-preview/

Pull request here: PR#47: Document multi repo local preview - fedora-docs/documentation-contributors-guide - Pagure.io

1 Like