docs: document some antora build details

[fhennig]

During the last release we encountered some issues involving xrefs, I have now updated the troubleshooting page and docs overview explanation to make the component structure and xref mechanism more clear.

related to: #637

[netlify]

✅ Deploy Preview for stackable-docs ready!

Name	Link
🔨 Latest commit	939671f
🔍 Latest deploy log	https://app.netlify.com/sites/stackable-docs/deploys/66b0987f057b81000823bdb1
😎 Deploy Preview	https://deploy-preview-644--stackable-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[NickLarsenNZ]

Thanks @fhennig

I also wonder if we can mimic the release branch process before the release (and before all of the dependent release branches exist)? Maybe it would catch the recent issues earlier.

[fhennig]

@NickLarsenNZ Yeah that would be nice. The issue happened because there were mistaken links from older versions onto stable. I think we purged them all now, so the issue cannot happen again. I'm more worried about new xrefs sneaking in that also reference 'home' explicitly.

The process to check for this in advance would be maybe to set pre-release to false in nightlyand see if anything breaks, but withouth publishing this change. I find it difficult to come up with a rigid process to do this, I'd lean towards not doing anything for now because of this. I feel like any sort of advance check would introduce too many new complexities that make it not worth it.