Add crosslinks to toc: in docset.yml

[theletterf]

This PR adds crosslinks as accepted item types in docset.yml toc directives.

For example:

toc:
  - file: index.md
  - title: External Documentation
    crosslink: docs-content://directory/file.md

[github-actions]

🔍 Preview links for changed docs

• docs/configure/content-set/navigation.md

[theletterf]

@Mpdreamz @bmorelli25 Wanted to give this one a try. Seems to work (check the Testing section, last two items).

If the code is ugly, please feel free to salvage whatever looks useful in this PR, or commit directly.

[theletterf]

@Mpdreamz Anything missing for this one? Minus the remaining comment.

[Mpdreamz]

Not sure @theletterf, I need some time to get to this PR still :)

[theletterf]

No probs!

[theletterf]

@Mpdreamz Seems like I broke link resolution with the last commit. Checking.

[Mpdreamz]

This PR is finally failing like I was expecting it too :)

https://github.com/elastic/docs-builder/actions/runs/17245378751/job/48933555065?pr=1615#step:5:154

The sitemap builder does not yet know about the new CrosslinkReference type, will amend the PR.

[Mpdreamz]

LGTM but want @cotti to review as well since I did a bunch of changes here as well.

[cotti]

👍

[theletterf]

Excitedly jumps around

Time to merge? :)

[KOTungseth]

Before you merge, I have questions:

• Where are we merging this change? Staging or Production? While this change may seem small, it has the potential to create a ripple of problems when used incorrectly. We would benefit from merging to only Staging and testing before we make it live in Production.
• Do we want to merge this change in our public-facing docs, or would it be better suited behind a log in where users can personalize their Docs experience? My vision for this type of functionality was always to live behind the Cloud account log in.
• Do we have docs that explain this functionality?
• Where did the requirement for this functionality come from?

[theletterf]

@KOTungseth The way this is being implemented is to allow crosslinks in the nav. In that sense, a doc will only exist once and in one repo only, but we'll be able to link to it from other navs.

Answering your questions:

• I see no issue with merging this in production, unless @Mpdreamz also sees it. The change has been extensively reviewed and considered. Personally, I don't see what problems this would cause, since we edit and own the nav files in most cases. For context, this would help solve some nav pains (https://github.com/elastic/docs-content-internal/issues/138, Adds an xlink to the toc that points to reconciled page docs-content#2811).
• I don't see the need for this feature to be behind a log in. First news about this, actually! Happy to learn about it.
• Yes, in this PR: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/1615/configure/content-set/navigation#adding-cross-links-in-navigation
• From Custom TOC/nav links #1593. An alternative solution was proposed that allowed external URLs, but we decided to try this one instead.

Use of crosslinks might be unnecessary if @georgewallace's proposal for a unified nav UI prospers, but that might take a while. In the meantime, the need to solve some immediate navigation pains seems to exist.

[theletterf]

@Mpdreamz Could you comment with @KOTungseth? Can we move ahead?

[yetanothertw]

👋 just adding another use-case for this feature:

The way this is being implemented is to allow crosslinks in the nav. In that sense, a doc will only exist once and in one repo only, but we'll be able to link to it from other navs.

I'm looking forward to this PR being merged as it will help with closing #2738 and #2218, and avoid duplicated pages and drifting info.

[shainaraskas]

@KOTungseth I view this as another tool in our toolbox to solve some of our visibility issues in a lightweight way. agree that we shouldn't use it everywhere all the time, but I would like to see it merged.

[KOTungseth]

Approved ✅

[Mpdreamz]

@theletterf 🙏 thanks for this big contribution and bearing with us! 😸

Please wait for a release with this change to production before actually using the feature, will ping when its on production.

Let's also trial 1/2 crosslinks in the navigation before going all in.

[theletterf]

@Mpdreamz Sounds good — thank you! Will start a small test after you give me green light to go ahead. :)