Merge branch 'main' into fix/forward-nested-layout-sections

Author: Mpdreamz

.github/CODEOWNERS

@@ -1 +1,2 @@
-*   @elastic/docs-engineering
+* @elastic/docs-engineering
+/docs/ @elastic/docs

README.md

@@ -25,8 +25,9 @@ Options:
   --force <bool?>            Force a full rebuild of the destination folder (Default: null)
 
 Commands:
-  generate    Converts a source markdown folder or file to an output folder
-  serve       Continuously serve a documentation folder at http://localhost:3000.
+  generate        Converts a source markdown folder or file to an output folder
+  serve           Continuously serve a documentation folder at http://localhost:3000.
+  diff validate   Validates redirect rules have been applied to the current branch.
     File systems changes will be reflected without having to restart the server.
 ```
 
@@ -118,6 +119,16 @@ https://github.com/elastic/{your-repository}/settings/pages
 
 ---
 
+## Validating redirection rules
+
+If documentation is moved, renamed or deleted, `docs-builder` can verify if changes in the working branch in relation to the default branch are reflected in the repository's `redirects.yml`. Verification in the local machine is currently supported.
+
+`docs-builder diff validate <path>`
+
+`<path>` is an optional parameter to customize the documentation folder path. It defaults to `docs`.
+
+---
+
 ## Run without docker
 
 You can use the .NET CLI to publish a self-contained `docs-builder` native code
@@ -140,7 +151,7 @@ existing surveyed tools
 
 # Local Development
 
-## Preqrequisites
+## Prerequisites
 
 - [.NET 9.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/9.0)
 - [Node.js 22.13.1 (LTS)](https://nodejs.org/en/blog/release/v22.13.1)

docs/contribute/index.md

@@ -24,6 +24,29 @@ To contribute to earlier versions of the Elastic Stack, you must work with our [
 * For **simple bugfixes and enhancements** --> [contribute on the web](on-the-web.md)
 * For **complex or multi-page updates** --> [Contribute locally](locally.md)
 
+Starting with Elastic Stack version 9.0, ECE 4.0, and ECK 3.0, a new set of docs is no longer published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes directly within the content using a [cumulative approach](#cumulative-docs).
+
+#### Write cumulative documentation [#cumulative-docs]
+
+Cumulative documentation means that one page can cover multiple product versions, deployment types, and release stages. Instead of creating separate pages for each release, we update the same page with version-specific details. 
+
+This helps readers understand which parts of the content apply to their own ecosystem and product versions, without needing to switch between different versions of a page.
+
+Following this approach, information for supported versions must not be removed unless it was never accurate. Instead, refactor the content to improve clarity or to include details for other products, deployment types, or versions.
+
+In order to achieve this, the markdown source files integrate a **tagging system** meant to identify:
+
+* Which Elastic products and deployment models the content applies to.
+* When a feature goes into a new state as compared to the established base version.
+
+This [tagging system](#applies-to) is mandatory for all of the public-facing documentation. 
+
+##### The `applies_to` tag [#applies-to]
+
+Use the [`applies_to`](../syntax/applies.md) tag to indicate which versions, deployment types, or release stages each part of the content is relevant to.
+
+You must always use the `applies_to` tag at the [page](../syntax/applies.md#page-annotations) level. Optionally, you can also use it at the [section](../syntax/applies.md#sections) or [inline](../syntax/applies.md#inline-applies-to) level if certain parts of the content apply only to specific versions, deployment types, or release stages.
+
 ## Report a bug
 
 * It's a **documentation** problem --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) *or* [Fix it myself](locally.md)
@@ -36,4 +59,4 @@ To contribute to earlier versions of the Elastic Stack, you must work with our [
 
 ## Work on docs-builder
 
-That sounds great! See [development](../development/index.md) to learn how to contribute to our documentation build system.
+That sounds great! See [development](../development/index.md) to learn how to contribute to our documentation build system.

src/Elastic.Documentation.LegacyDocs/BloomFilter.cs

@@ -141,14 +141,16 @@ public void Save(string filePath)
 	}
 
 	/// <summary>
-	/// Loads a Bloom Filter from a binary file.
+	/// Loads a Bloom Filter from a stream.
+	/// The stream is expected to contain data in the same format as Save() produces.
 	/// </summary>
-	/// <param name="filePath">The path to the file containing the filter data.</param>
+	/// <param name="stream">The stream containing the filter data.</param>
 	/// <returns>A new BloomFilter instance.</returns>
-	public static BloomFilter Load(string filePath)
+	public static BloomFilter Load(Stream stream)
 	{
-		using var stream = File.OpenRead(filePath);
-		using var reader = new BinaryReader(stream);
+		// Use a BinaryReader, but leave the stream open as it's managed externally.
+		using var reader = new BinaryReader(stream, Encoding.UTF8, leaveOpen: true);
+
 		// 1. Read metadata (Size and HashCount)
 		var size = reader.ReadInt32();
 		var hashCount = reader.ReadInt32();

src/Elastic.Documentation.LegacyDocs/LegacyPageChecker.cs

@@ -2,15 +2,17 @@
 // 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.Documentation.Configuration;
 
 namespace Elastic.Documentation.LegacyDocs;
 
-public class LegacyPageChecker(IFileSystem fs)
+public class LegacyPageChecker
 {
 	private BloomFilter? _bloomFilter;
-	private readonly string _bloomFilterBinaryPath = Path.Combine(Paths.WorkingDirectoryRoot.FullName, "src", "Elastic.Documentation.LegacyDocs", "legacy-pages.bloom.bin");
+	private const string RootNamespace = "Elastic.Documentation.LegacyDocs";
+	private const string FileName = "legacy-pages.bloom.bin";
+	private const string ResourceName = $"{RootNamespace}.{FileName}";
+	private readonly string _bloomFilterBinaryPath = Path.Combine(Paths.WorkingDirectoryRoot.FullName, "src", RootNamespace, FileName);
 
 
 	public bool PathExists(string path)
@@ -19,11 +21,13 @@ public bool PathExists(string path)
 		return _bloomFilter.Check(path);
 	}
 
-	private BloomFilter LoadBloomFilter()
+	private static BloomFilter LoadBloomFilter()
 	{
-		var bloomFilterBinaryInfo = fs.FileInfo.New(_bloomFilterBinaryPath);
-		_bloomFilter ??= BloomFilter.Load(bloomFilterBinaryInfo.FullName);
-		return _bloomFilter;
+		var assembly = typeof(LegacyPageChecker).Assembly;
+		using var stream = assembly.GetManifestResourceStream(ResourceName) ?? throw new FileNotFoundException(
+			$"Embedded resource '{ResourceName}' not found in assembly '{assembly.FullName}'. " +
+			"Ensure the Build Action for 'legacy-pages.bloom.bin' is 'Embedded Resource' and the path/name is correct.");
+		return BloomFilter.Load(stream);
 	}
 
 	public void GenerateBloomFilterBinary(IPagesProvider pagesProvider)

src/Elastic.Documentation.Site/package-lock.json

@@ -36,7 +36,7 @@
     "@r2wc/react-to-web-component": "^2.0.4",
     "@tailwindcss/postcss": "4.1.10",
     "@trivago/prettier-plugin-sort-imports": "5.2.2",
-    "eslint": "9.28.0",
+    "eslint": "9.29.0",
     "globals": "16.2.0",
     "moment": "^2.30.1",
     "parcel": "2.15.2",

src/Elastic.Documentation.Site/package.json

@@ -11,7 +11,7 @@ public record LegacyPageMapping(string RawUrl, string Version, bool Exists)
 
 public interface ILegacyUrlMapper
 {
-	IReadOnlyCollection<LegacyPageMapping> MapLegacyUrl(IReadOnlyCollection<string>? mappedPages);
+	IReadOnlyCollection<LegacyPageMapping>? MapLegacyUrl(IReadOnlyCollection<string>? mappedPages);
 }
 
 public record NoopLegacyUrlMapper : ILegacyUrlMapper

src/Elastic.Documentation/Legacy/ILegacyUrlMapper.cs

@@ -110,9 +110,9 @@ private async Task<string> RenderLayout(MarkdownFile markdown, MarkdownDocument
 			Features = DocumentationSet.Configuration.Features,
 			StaticFileContentHashProvider = StaticFileContentHashProvider,
 			ReportIssueUrl = reportUrl,
-			CurrentVersion = legacyPages.Count > 0 ? legacyPages.ElementAt(0).Version : "9.0+",
-			LegacyPages = legacyPages.Skip(1).ToArray(),
-			VersionDropdownItems = VersionDrownDownItemViewModel.FromLegacyPageMappings(legacyPages.Skip(1).ToArray()),
+			CurrentVersion = legacyPages?.Count > 0 ? legacyPages.ElementAt(0).Version : "9.0+",
+			LegacyPages = legacyPages?.Skip(1).ToArray(),
+			VersionDropdownItems = VersionDrownDownItemViewModel.FromLegacyPageMappings(legacyPages?.Skip(1).ToArray()),
 			Products = allProducts
 		});
 		return await slice.RenderAsync(cancellationToken: ctx);

src/Elastic.Markdown/Slices/HtmlWriter.cs

@@ -33,9 +33,9 @@ public class IndexViewModel
 	public required INavigationItem[] Parents { get; init; }
 
 	public required string NavigationHtml { get; init; }
-	public required string? CurrentVersion { get; init; }
-	public required LegacyPageMapping[] LegacyPages { get; init; }
-	public required VersionDrownDownItemViewModel[] VersionDropdownItems { get; init; }
+	public required string CurrentVersion { get; init; }
+	public required LegacyPageMapping[]? LegacyPages { get; init; }
+	public required VersionDrownDownItemViewModel[]? VersionDropdownItems { get; init; }
 	public required string? UrlPathPrefix { get; init; }
 	public required string? GithubEditUrl { get; init; }
 	public required string? ReportIssueUrl { get; init; }
@@ -63,8 +63,12 @@ public class VersionDrownDownItemViewModel
 	public required VersionDrownDownItemViewModel[]? Children { get; init; }
 
 	// This logic currently only handles one level of children. Although the model supports multiple levels, it is not currently used.
-	public static VersionDrownDownItemViewModel[] FromLegacyPageMappings(LegacyPageMapping[] legacyPageMappings)
+	public static VersionDrownDownItemViewModel[]? FromLegacyPageMappings(LegacyPageMapping[]? legacyPageMappings)
 	{
+		if (legacyPageMappings is null)
+		{
+			return null;
+		}
 		var groupedVersions = GroupByMajorVersion(legacyPageMappings);
 		return groupedVersions.Select(m =>
 		{