Add links to tocs

Author: theletterf

docs/configure/content-set/navigation.md

@@ -148,6 +148,39 @@ It [may be linked to locally however](../../developer-notes.md)
 
 #### Nesting `toc`
 
+The `toc` key can include nested `toc.yml` files.
+
+The following example includes two sub-`toc.yml` files located in directories named `elastic-basics` and `solutions`:
+
+```yml
+toc:
+  - file: index.md
+  - toc: elastic-basics
+  - toc: solutions
+```
+
+#### External links
+
+You can include links to external websites directly in your navigation tree. Use the `link` key with a valid URL, and provide a human-friendly `title`.
+
+```yaml
+toc:
+  - link: https://elastic.co
+    title: Elastic Website
+  - toc: getting-started
+  - link: https://github.com/elastic/docs-builder
+    title: Docs Builder Repository
+```
+
+Docs-builder renders external links with an icon, opens them in a new tab, and adds `rel="noopener noreferrer"` for security.
+
+Best practices:
+
+* Use external links sparingly in your primary navigation, placing them near the bottom of a section when possible.
+* Provide clear titles that indicate the link leads to an external resource.
+* Periodically verify that external URLs remain valid, and update them if destinations change.
+
+
 The `toc` key can include nested `toc.yml` files.
 
 The following example includes two sub-`toc.yml` files located in directories named `elastic-basics` and `solutions`:

src/Elastic.Documentation.Configuration/Builder/TableOfContentsConfiguration.cs

@@ -130,6 +130,8 @@ private IReadOnlyCollection<ITocItem> ReadChildren(YamlStreamReader reader, KeyV
 	{
 		string? file = null;
 		string? folder = null;
+		string? link = null;
+		string? linkTitle = null;
 		string[]? detectionRules = null;
 		TableOfContentsConfiguration? toc = null;
 		var detectionRulesFound = false;
@@ -148,6 +150,12 @@ private IReadOnlyCollection<ITocItem> ReadChildren(YamlStreamReader reader, KeyV
 					hiddenFile = key == "hidden";
 					file = ReadFile(reader, entry, parentPath);
 					break;
+				case "link":
+					link = reader.ReadString(entry);
+					break;
+				case "title":
+					linkTitle = reader.ReadString(entry);
+					break;
 				case "folder":
 					folder = ReadFolder(reader, entry, parentPath);
 					parentPath += $"{Path.DirectorySeparatorChar}{folder}";
@@ -199,6 +207,15 @@ private IReadOnlyCollection<ITocItem> ReadChildren(YamlStreamReader reader, KeyV
 			return [new FileReference(this, path, hiddenFile, children ?? [])];
 		}
 
+		if (link is not null)
+		{
+			// external links cannot have children
+			if (children is not null)
+				reader.EmitWarning("'link' entries may not contain 'children'", tocEntry);
+
+			return [new LinkReference(this, link, linkTitle ?? link)];
+		}
+
 		if (folder is not null)
 		{
 			if (children is null)

src/Elastic.Documentation.Configuration/TableOfContents/ITocItem.cs

@@ -27,15 +27,15 @@ public record TocReference(Uri Source, ITableOfContentsScope TableOfContentsScop
 	/// A phantom table of contents is a table of contents that is not rendered in the UI but is used to generate the TOC.
 	/// This should be used sparingly and needs explicit configuration in navigation.yml.
 	/// It's typically used for container TOC that holds various other TOC's where its children are rehomed throughout the navigation.
-	/// <para>Examples of phantom toc's:</para>
-	/// <list type="">
-	///		<item> - toc: elasticsearch://reference</item>
-	///		<item> - toc: docs-content://</item>
-	/// </list>
-	/// <para>Because navigation.yml does exhaustive checks to ensure all toc.yml files are referenced, marking these containers as phantoms
-	/// ensures that these skip validation checks
-	/// </para>
 	/// </summary>
 	public bool IsPhantom { get; init; }
 }
 
+/// <summary>
+/// Represents an external link in the table of contents.
+/// </summary>
+/// <param name="TableOfContentsScope">Scope this link belongs to.</param>
+/// <param name="Url">Absolute URL of the external resource.</param>
+/// <param name="Title">Display title for the link.</param>
+public record LinkReference(ITableOfContentsScope TableOfContentsScope, string Url, string Title) : ITocItem;
+

src/Elastic.Markdown/IO/Navigation/DocumentationGroup.cs

@@ -6,6 +6,7 @@
 using Elastic.Documentation;
 using Elastic.Documentation.Configuration;
 using Elastic.Documentation.Configuration.TableOfContents;
+using Elastic.Markdown.IO.Navigation; // for ExternalLinkNavigationItem
 using Elastic.Documentation.Extensions;
 using Elastic.Documentation.Site.Navigation;
 
@@ -178,6 +179,11 @@ void AddToNavigationItems(INavigationItem item, ref int fileIndex)
 				if (indexFile != md)
 					AddToNavigationItems(new FileNavigationItem(md, this, file.Hidden), ref fileIndex);
 			}
+			else if (tocItem is LinkReference extLink)
+			{
+				var nav = new ExternalLinkNavigationItem(extLink.Url, extLink.Title, this);
+				AddToNavigationItems(nav, ref fileIndex);
+			}
 			else if (tocItem is FolderReference folder)
 			{
 				var children = folder.Children;

src/Elastic.Markdown/IO/Navigation/ExternalLinkNavigationItem.cs

@@ -0,0 +1,26 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using Elastic.Documentation.Site.Navigation;
+
+namespace Elastic.Markdown.IO.Navigation;
+
+/// <summary>
+/// Navigation item representing an external URL in the TOC.
+/// </summary>
+public record ExternalLinkNavigationItem(string ExternalUrl, string Title, DocumentationGroup Group)
+	: INavigationItem
+{
+	public INodeNavigationItem<INavigationModel, INavigationItem>? Parent { get; set; } = Group;
+
+	public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot { get; } = Group.NavigationRoot;
+
+	public string Url => ExternalUrl;
+
+	public string NavigationTitle => Title;
+
+	public int NavigationIndex { get; set; }
+
+	public bool Hidden => false;
+}