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:
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?
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.
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
+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:
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: