Skip to content

Commit 8d6c67a

Browse files
Mpdreamzshainaraskas
Mpdreamz
and
shainaraskas
authored
Add redirects.yml to publish renames/delations in links.json for dependent docsets. (#556)
* Add redirect information to docset.yml * Support all scenarios * add documentation for redirects * move redirects to separate file * add target validation for redirect files and anchors * fix accidental touch of pages-nav.ts * fix failing testS * update tests to use real redirect and anchor page data * Update docs/contribute/redirects.md Co-authored-by: shainaraskas <[email protected]> --------- Co-authored-by: shainaraskas <[email protected]>
1 parent 9dc8805 commit 8d6c67a

30 files changed

+1119
-229
lines changed

‎.editorconfig‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -224,13 +224,18 @@ dotnet_diagnostic.IDE0001.severity = none
224224

225225
dotnet_diagnostic.IDE0057.severity = none
226226

227+
dotnet_diagnostic.IDE0051.severity = suggestion
228+
dotnet_diagnostic.IDE0059.severity = suggestion
229+
227230
[DocumentationWebHost.cs]
228231
dotnet_diagnostic.IL3050.severity = none
229232
dotnet_diagnostic.IL2026.severity = none
230233

234+
235+
231236
[tests/**/*.cs]
232237
dotnet_diagnostic.IDE0058.severity = none
233-
238+
dotnet_diagnostic.IDE0022.severity = none
234239

235240
[*.{sh,bat,ps1}]
236241
trim_trailing_whitespace=true

docs/docset.yml renamed to docs/_docset.yml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ toc:
1818
- file: locally.md
1919
- file: on-the-web.md
2020
- file: move.md
21+
- file: redirects.md
2122
- folder: migration
2223
children:
2324
- file: index.md
@@ -97,6 +98,12 @@ toc:
9798
children:
9899
- file: first-page.md
99100
- file: second-page.md
101+
- folder: redirects
102+
children:
103+
- file: first-page.md
104+
- file: second-page.md
105+
- file: third-page.md
106+
- file: 5th-page.md
100107
- folder: deeply-nested
101108
children:
102109
- file: index.md

‎docs/_redirects.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
redirects:
2+
'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md'
3+
'testing/redirects/9th-page.md': '!testing/redirects/5th-page.md'
4+
'testing/redirects/6th-page.md':
5+
'testing/redirects/7th-page.md':
6+
to: 'testing/redirects/5th-page.md'
7+
anchors: '!'
8+
'testing/redirects/first-page-old.md':
9+
to: 'testing/redirects/second-page.md'
10+
anchors:
11+
'old-anchor': 'active-anchor'
12+
'removed-anchor':
13+
'testing/redirects/second-page-old.md':
14+
many:
15+
- to: "testing/redirects/second-page.md"
16+
anchors:
17+
"aa": "zz"
18+
"removed-anchor":
19+
- to: "testing/redirects/third-page.md"
20+
anchors:
21+
"yy": "bb"
22+
'testing/redirects/third-page.md':
23+
anchors:
24+
'removed-anchor':

‎docs/contribute/redirects.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
navigation_title: "Redirects"
3+
---
4+
# Adding redirects to link resolving
5+
6+
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).
7+
8+
Redirects allow you to force other documentation sets to resolve old links to their new location.
9+
This allows you to publish your changes and work to update the other documentation sets.
10+
11+
## File location.
12+
13+
The file should be located next to your `docset.yml` file
14+
15+
* `redirects.yml` if you use `docset.yml`
16+
* `_redirects.yml` if you use `_docset.yml`
17+
18+
## Syntax
19+
20+
A full overview of the syntax, don't worry we'll zoom after!
21+
22+
```yaml
23+
redirects:
24+
'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md'
25+
'testing/redirects/9th-page.md': '!testing/redirects/5th-page.md'
26+
'testing/redirects/6th-page.md':
27+
'testing/redirects/7th-page.md':
28+
to: 'testing/redirects/5th-page.md'
29+
anchors: '!'
30+
'testing/redirects/first-page-old.md':
31+
to: 'testing/redirects/second-page.md'
32+
anchors:
33+
'old-anchor': 'active-anchor'
34+
'removed-anchor':
35+
'testing/redirects/second-page-old.md':
36+
many:
37+
- to: "testing/redirects/second-page.md"
38+
anchors:
39+
"aa": "zz"
40+
"removed-anchor":
41+
- to: "testing/redirects/third-page.md"
42+
anchors:
43+
"bb": "yy"
44+
'testing/redirects/third-page.md':
45+
anchors:
46+
'removed-anchor':
47+
```
48+
49+
### Redirect preserving all anchors
50+
51+
This will rewrite `4th-page.md#anchor` to `5th-page#anchor` while still validating the
52+
anchor is valid like normal.
53+
54+
```yaml
55+
redirects:
56+
'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md'
57+
```
58+
### Redirect stripping all anchors
59+
60+
Here both `9th-page.md` and `7th-page.md` redirect to `5th-page.md` but the crosslink resolver
61+
will strip any anchors on `9th-page.md` and `7th-page.md`.
62+
63+
:::{note}
64+
The following two are equivalent. The `!` prefix provides a convenient shortcut
65+
:::
66+
67+
```yaml
68+
redirects:
69+
'testing/redirects/9th-page.md': '!testing/redirects/5th-page.md'
70+
'testing/redirects/7th-page.md':
71+
to: 'testing/redirects/5th-page.md'
72+
anchors: '!'
73+
```
74+
75+
A special case is redirecting to the page itself when a section gets removed/renamed.
76+
In which case `to:` can simply be omitted
77+
78+
```yaml
79+
'testing/redirects/third-page.md':
80+
anchors:
81+
'removed-anchor':
82+
```
83+
84+
### Redirect renaming anchors
85+
86+
* `first-page-old.md#old-anchor` will redirect to `second-page.md#active-anchor`
87+
* `first-page-old.md#removed-anchor` will redirect to `second-page.md`
88+
89+
Any anchor not listed will be forwarded and validated e.g;
90+
91+
* `first-page-old.md#another-anchor` will redirect to `second-page.md#another-anchor` and validate
92+
`another-anchor` exists in `second-page.md`
93+
94+
```yaml
95+
redirects:
96+
'testing/redirects/first-page-old.md':
97+
to: 'testing/redirects/second-page.md'
98+
anchors:
99+
'old-anchor': 'active-anchor'
100+
'removed-anchor':
101+
```

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# This acts as a redirect target
2+
3+
4+
## Another anchor [bb]

‎docs/testing/redirects/first-page.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# This is 1 redirecting to 2
2+
3+
4+
1 is redirecting to 2
5+
6+
7+
## Has an anchor as well

‎docs/testing/redirects/second-page.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# This is 2 redirecting to 1
2+
3+
4+
2 is redirecting to 1
5+
6+
7+
## A different anchor [active-anchor]
8+
9+
## Anchor ZZ [zz]
10+
11+
Some content
12+
13+
## Anchor YY [yy]
14+
15+
Some content

‎docs/testing/redirects/third-page.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# This acts as a redirect target
2+
3+
4+
## Another anchor [bb]

‎src/Elastic.Markdown/BuildContext.cs‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
// Licensed to Elasticsearch B.V under one or more agreements.
22
// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
33
// See the LICENSE file in the project root for more information
4+
45
using System.IO.Abstractions;
56
using Elastic.Markdown.Diagnostics;
67
using Elastic.Markdown.IO;
8+
using Elastic.Markdown.IO.Configuration;
79
using Elastic.Markdown.IO.Discovery;
810

911
namespace Elastic.Markdown;
@@ -20,7 +22,7 @@ public record BuildContext
2022

2123
public GitCheckoutInformation Git { get; }
2224

23-
public required DiagnosticsCollector Collector { get; init; }
25+
public DiagnosticsCollector Collector { get; }
2426

2527
public bool Force { get; init; }
2628

@@ -36,13 +38,17 @@ public string? UrlPathPrefix
3638
private readonly string? _urlPathPrefix;
3739

3840
public BuildContext(IFileSystem fileSystem)
39-
: this(fileSystem, fileSystem, null, null) { }
41+
: this(new DiagnosticsCollector([]), fileSystem, fileSystem, null, null) { }
42+
43+
public BuildContext(DiagnosticsCollector collector, IFileSystem fileSystem)
44+
: this(collector, fileSystem, fileSystem, null, null) { }
4045

41-
public BuildContext(IFileSystem readFileSystem, IFileSystem writeFileSystem)
42-
: this(readFileSystem, writeFileSystem, null, null) { }
46+
public BuildContext(DiagnosticsCollector collector, IFileSystem readFileSystem, IFileSystem writeFileSystem)
47+
: this(collector, readFileSystem, writeFileSystem, null, null) { }
4348

44-
public BuildContext(IFileSystem readFileSystem, IFileSystem writeFileSystem, string? source, string? output)
49+
public BuildContext(DiagnosticsCollector collector, IFileSystem readFileSystem, IFileSystem writeFileSystem, string? source, string? output)
4550
{
51+
Collector = collector;
4652
ReadFileSystem = readFileSystem;
4753
WriteFileSystem = writeFileSystem;
4854

@@ -60,8 +66,11 @@ public BuildContext(IFileSystem readFileSystem, IFileSystem writeFileSystem, str
6066
SourcePath = ConfigurationPath.Directory!;
6167

6268
Git = GitCheckoutInformation.Create(ReadFileSystem);
69+
Configuration = new ConfigurationFile(ConfigurationPath, SourcePath, this);
6370
}
6471

72+
public ConfigurationFile Configuration { get; set; }
73+
6574
private (IDirectoryInfo, IFileInfo) FindDocsFolderFromRoot(IDirectoryInfo rootPath)
6675
{
6776
string[] files = ["docset.yml", "_docset.yml"];
@@ -86,5 +95,4 @@ from folder in knownFolders
8695

8796
return (docsFolder, configurationPath);
8897
}
89-
9098
}

0 commit comments

Comments
 (0)