Skip to content

Add external links to navigation #1613

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 9 commits into
base: main
Choose a base branch
from

Conversation

theletterf
Copy link
Contributor

Fixes #1593

Copy link

github-actions bot commented Jul 25, 2025

🔍 Preview links for changed docs

@theletterf
Copy link
Contributor Author

@bmorelli25 See the GitHub repository link in https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/1613/configure/content-set/navigation

@leemthompo
Copy link
Contributor

oooooh I immediately want to use this to add a link to the Elasticsearch reference docs in the Elasticsearch solution nav 😍

would this be a valid use case?

@bmorelli25
Copy link
Member

would this be a valid use case?

There's a thread in #elastic-docs-v3 about this. There are two use cases and that's the other one. Not sure if Fabri is also working on that 🧙

@theletterf
Copy link
Contributor Author

@Mpdreamz @bmorelli25 After melting Claude's brain, it looks like adding crosslinks validation and rendering to the toc is too much. LLMs being unable to figure this out suggests that crosslinks depend deeply on the overall architecture, but correct me if I'm wrong.

For a quick solution, I'd rather show external links as they appear now and, if they start with elastic.co/docs, open them as if they were normal toc links (no icon, no _blank target). How does that sound?

@Mpdreamz
Copy link
Member

Mpdreamz commented Jul 25, 2025

I am going to mull over this one over the weekend. For sure I don't want links to elastic.co/docs using this mechanism that should result in an error.

We could support:

link: docs-content://a/b/c.md

@Mpdreamz
Copy link
Member

image

The styling of navigation items has changed as part of this PR.

@theletterf
Copy link
Contributor Author

theletterf commented Jul 25, 2025

@Mpdreamz I love that. Any hint on how to achieve that though? I mean the crosslinks in the toc.

@Mpdreamz
Copy link
Member

You need the current ICrossLinkUrlResolver, I think it's best to to this in two phases.

Tree = new TableOfContentsTree(Source, Context, lookups, treeCollector, ref fileIndex);

After Tree is build iterate over it to validate all cross links.

We already do something similar to ensure the validity of navigation index:

UpdateNavigationIndex(Tree.NavigationItems, ref navigationIndex);

@theletterf
Copy link
Contributor Author

CSS issue solved for this particular PR, @Mpdreamz! We shouldn't abuse this system though, I agree.

@theletterf
Copy link
Contributor Author

We can probably close this one if #1615 gets merged, though it'd be a separate functionality.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Custom TOC/nav links
4 participants