Add redirects.yml to publish renames/delations in links.json for dependent docsets.

.editorconfig

@@ -224,13 +224,18 @@ dotnet_diagnostic.IDE0001.severity = none
 
 dotnet_diagnostic.IDE0057.severity = none
 
+dotnet_diagnostic.IDE0051.severity = suggestion
+dotnet_diagnostic.IDE0059.severity = suggestion
+
 [DocumentationWebHost.cs]
 dotnet_diagnostic.IL3050.severity = none
 dotnet_diagnostic.IL2026.severity = none
 
+
+
 [tests/**/*.cs]
 dotnet_diagnostic.IDE0058.severity = none
-
+dotnet_diagnostic.IDE0022.severity = none
 
 [*.{sh,bat,ps1}]
 trim_trailing_whitespace=true

docs/docset.yml → docs/_docset.yml

@@ -18,6 +18,7 @@ toc:
       - file: locally.md
       - file: on-the-web.md
       - file: move.md
+      - file: redirects.md
   - folder: migration
     children:
       - file: index.md
@@ -97,6 +98,12 @@ toc:
         children:
           - file: first-page.md
           - file: second-page.md
+      - folder: redirects
+        children:
+          - file: first-page.md
+          - file: second-page.md
+          - file: third-page.md
+          - file: 5th-page.md
       - folder: deeply-nested
         children:
           - file: index.md

docs/_redirects.yml

@@ -0,0 +1,24 @@
+redirects:
+  'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md'
+  'testing/redirects/9th-page.md': '!testing/redirects/5th-page.md'
+  'testing/redirects/6th-page.md':
+  'testing/redirects/7th-page.md':
+    to: 'testing/redirects/5th-page.md'
+    anchors: '!'
+  'testing/redirects/first-page-old.md':
+    to: 'testing/redirects/second-page.md'
+    anchors:
+      'old-anchor': 'active-anchor'
+      'removed-anchor':
+  'testing/redirects/second-page-old.md':
+    many:
+      - to: "testing/redirects/second-page.md"
+        anchors:
+          "aa": "zz"
+          "removed-anchor":
+      - to: "testing/redirects/third-page.md"
+        anchors:
+          "yy": "bb"
+  'testing/redirects/third-page.md':
+    anchors:
+      'removed-anchor':

docs/contribute/redirects.md

@@ -0,0 +1,101 @@
+---
+navigation_title: "Redirects"
+---
+# Adding redirects to link resolving
+
+If you [move files around](move.md) or simply need to delete a few pages you might end up in a chicken-and-egg situation. The files you move or delete might still be linked to by other [documentation sets](../configure/content-set/index.md).
+
+Redirects allow you to force other documentation sets to resolve old links to their new location.
+This allows you to publish your changes and work to update the other documentation sets.
+
+## File location.
+
+The file should be located next to your `docset.yml` file
+
+* `redirects.yml` if you use `docset.yml`
+* `_redirects.yml` if you use `_docset.yml`
+
+## Syntax
+
+A full overview of the syntax, don't worry we'll zoom after!
+
+```yaml
+redirects:
+  'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md'
+  'testing/redirects/9th-page.md': '!testing/redirects/5th-page.md'
+  'testing/redirects/6th-page.md':
+  'testing/redirects/7th-page.md':
+    to: 'testing/redirects/5th-page.md'
+    anchors: '!'
+  'testing/redirects/first-page-old.md':
+    to: 'testing/redirects/second-page.md'
+    anchors:
+      'old-anchor': 'active-anchor'
+      'removed-anchor':
+  'testing/redirects/second-page-old.md':
+    many:
+      - to: "testing/redirects/second-page.md"
+        anchors:
+          "aa": "zz"
+          "removed-anchor":
+      - to: "testing/redirects/third-page.md"
+        anchors:
+          "bb": "yy"
+  'testing/redirects/third-page.md':
+    anchors:
+      'removed-anchor':
+```
+
+### Redirect preserving all anchors
+
+This will rewrite `4th-page.md#anchor` to `5th-page#anchor` while still validating the 
+anchor is valid like normal.
+
+```yaml
+redirects:
+  'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md'
+```
+### Redirect stripping all anchors
+
+Here both `9th-page.md` and `7th-page.md` redirect to `5th-page.md` but the crosslink resolver
+will strip any anchors on `9th-page.md` and `7th-page.md`.
+
+:::{note}
+The following two are equivalent. The `!` prefix provides a convenient shortcut
+:::
+
+```yaml
+redirects:
+  'testing/redirects/9th-page.md': '!testing/redirects/5th-page.md'
+  'testing/redirects/7th-page.md':
+    to: 'testing/redirects/5th-page.md'
+    anchors: '!'
+```
+
+A special case is redirecting to the page itself when a section gets removed/renamed.
+In which case `to:` can simply be omitted
+
+```yaml
+  'testing/redirects/third-page.md':
+    anchors:
+      'removed-anchor':
+```
+
+### Redirect renaming anchors
+
+* `first-page-old.md#old-anchor` will redirect to `second-page.md#active-anchor`
+* `first-page-old.md#removed-anchor` will redirect to `second-page.md`
+
+Any anchor not listed will be forwarded and validated e.g;
+
+* `first-page-old.md#another-anchor` will redirect to `second-page.md#another-anchor` and validate 
+  `another-anchor` exists in `second-page.md`
+
+```yaml
+redirects:
+  'testing/redirects/first-page-old.md':
+    to: 'testing/redirects/second-page.md'
+    anchors:
+      'old-anchor': 'active-anchor'
+      'removed-anchor':
+```

docs/testing/redirects/5th-page.md

@@ -0,0 +1,4 @@
+# This acts as a redirect target
+
+
+## Another anchor [bb]

docs/testing/redirects/first-page.md

@@ -0,0 +1,7 @@
+# This is 1 redirecting to 2
+
+
+1 is redirecting to 2
+
+
+## Has an anchor as well

docs/testing/redirects/second-page.md

@@ -0,0 +1,15 @@
+# This is 2 redirecting to 1
+
+
+2 is redirecting to 1
+
+
+## A different anchor [active-anchor]
+
+## Anchor ZZ [zz]
+
+Some content
+
+## Anchor YY [yy]
+
+Some content

docs/testing/redirects/third-page.md

@@ -0,0 +1,4 @@
+# This acts as a redirect target
+
+
+## Another anchor [bb]

src/Elastic.Markdown/BuildContext.cs

@@ -1,9 +1,11 @@
 // 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 System.IO.Abstractions;
 using Elastic.Markdown.Diagnostics;
 using Elastic.Markdown.IO;
+using Elastic.Markdown.IO.Configuration;
 using Elastic.Markdown.IO.Discovery;
 
 namespace Elastic.Markdown;
@@ -20,7 +22,7 @@ public record BuildContext
 
 	public GitCheckoutInformation Git { get; }
 
-	public required DiagnosticsCollector Collector { get; init; }
+	public DiagnosticsCollector Collector { get; }
 
 	public bool Force { get; init; }
 
@@ -36,13 +38,17 @@ public string? UrlPathPrefix
 	private readonly string? _urlPathPrefix;
 
 	public BuildContext(IFileSystem fileSystem)
-		: this(fileSystem, fileSystem, null, null) { }
+		: this(new DiagnosticsCollector([]), fileSystem, fileSystem, null, null) { }
+
+	public BuildContext(DiagnosticsCollector collector, IFileSystem fileSystem)
+		: this(collector, fileSystem, fileSystem, null, null) { }
 
-	public BuildContext(IFileSystem readFileSystem, IFileSystem writeFileSystem)
-		: this(readFileSystem, writeFileSystem, null, null) { }
+	public BuildContext(DiagnosticsCollector collector, IFileSystem readFileSystem, IFileSystem writeFileSystem)
+		: this(collector, readFileSystem, writeFileSystem, null, null) { }
 
-	public BuildContext(IFileSystem readFileSystem, IFileSystem writeFileSystem, string? source, string? output)
+	public BuildContext(DiagnosticsCollector collector, IFileSystem readFileSystem, IFileSystem writeFileSystem, string? source, string? output)
 	{
+		Collector = collector;
 		ReadFileSystem = readFileSystem;
 		WriteFileSystem = writeFileSystem;
 
@@ -60,8 +66,11 @@ public BuildContext(IFileSystem readFileSystem, IFileSystem writeFileSystem, str
 			SourcePath = ConfigurationPath.Directory!;
 
 		Git = GitCheckoutInformation.Create(ReadFileSystem);
+		Configuration = new ConfigurationFile(ConfigurationPath, SourcePath, this);
 	}
 
+	public ConfigurationFile Configuration { get; set; }
+
 	private (IDirectoryInfo, IFileInfo) FindDocsFolderFromRoot(IDirectoryInfo rootPath)
 	{
 		string[] files = ["docset.yml", "_docset.yml"];
@@ -86,5 +95,4 @@ from folder in knownFolders
 
 		return (docsFolder, configurationPath);
 	}
-
 }