Various refactors

Author: theletterf

docs/cli/docset/format.md

@@ -1,6 +1,6 @@
 # format
 
-Format documentation files by fixing common issues like irregular whitespace
+Format documentation files by fixing common issues like irregular space
 
 ## Usage
 
@@ -20,19 +20,19 @@ docs-builder format [options...] [-h|--help] [--version]
 
 The `format` command automatically detects and fixes formatting issues in your documentation files. The command only processes Markdown files (`.md`) that are included in your `_docset.yml` table of contents, ensuring that only intentional documentation files are modified.
 
-Currently, it handles irregular whitespace characters that may impair Markdown rendering.
+Currently, it handles irregular space characters that may impair Markdown rendering.
 
-### Irregular Whitespace Detection
+### Irregular Space Detection
 
-The format command detects and replaces 24 types of irregular whitespace characters with regular spaces, including:
+The format command detects and replaces 24 types of irregular space characters with regular spaces, including:
 
 - No-Break Space (U+00A0)
 - En Space (U+2002)
 - Em Space (U+2003)
 - Zero Width Space (U+200B)
 - Line Separator (U+2028)
 - Paragraph Separator (U+2029)
-- And 18 other irregular whitespace variants
+- And 18 other irregular space variants
 
 These characters can cause unexpected rendering issues in Markdown and are often introduced accidentally through copy-paste operations from other applications.
 
@@ -62,8 +62,8 @@ The command provides detailed feedback about the formatting process:
 
 ```
 Formatting documentation in: /path/to/docs
-Fixed 2 irregular whitespace(s) in: guide/setup.md
-Fixed 1 irregular whitespace(s) in: api/endpoints.md
+Fixed 2 irregular space(s) in: guide/setup.md
+Fixed 1 irregular space(s) in: api/endpoints.md
 
 Formatting complete:
   Files processed: 155

docs/index.md

@@ -4,9 +4,9 @@ navigation_title: Elastic Docs v3
 
 # Welcome to Elastic Docs v3
 
-Elastic Docs V3 is our next-generation documentation platform designed to improve the experience of learning, using, and contributing to Elastic products. Built on a foundation of modern authoring tools and scalable infrastructure, V3 offers faster builds, streamlined versioning, and enhanced navigation to guide users through Elastic’s complex ecosystem.
+Elastic Docs V3 is our next-generation documentation platform designed to improve the experience of learning, using, and contributing to Elastic products. Built on a foundation of modern authoring tools and scalable infrastructure, V3 offers faster builds, streamlined versioning, and enhanced navigation to guide users through Elastic’s complex ecosystem.
 
-## What do you want to do today?
+## What do you want to do today?
 
 * [Contribute to Elastic documentation](./contribute/index.md)
 * [Learn about migration to Elastic Docs V3](./migration/index.md)

src/Elastic.Markdown/Myst/Linters/SpaceNormalizer.cs

@@ -0,0 +1,108 @@
+// 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.Buffers;
+using Elastic.Markdown.Diagnostics;
+using Markdig;
+using Markdig.Helpers;
+using Markdig.Parsers;
+using Markdig.Parsers.Inlines;
+using Markdig.Renderers;
+using Markdig.Renderers.Html;
+using Markdig.Renderers.Html.Inlines;
+using Markdig.Syntax.Inlines;
+
+namespace Elastic.Markdown.Myst.Linters;
+
+public static class SpaceNormalizerBuilderExtensions
+{
+	public static MarkdownPipelineBuilder UseSpaceNormalizer(this MarkdownPipelineBuilder pipeline)
+	{
+		pipeline.Extensions.AddIfNotAlready<SpaceNormalizerBuilderExtension>();
+		return pipeline;
+	}
+}
+
+public class SpaceNormalizerBuilderExtension : IMarkdownExtension
+{
+	public void Setup(MarkdownPipelineBuilder pipeline) =>
+		pipeline.InlineParsers.InsertBefore<EmphasisInlineParser>(new SpaceNormalizerParser());
+
+	public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer) =>
+		renderer.ObjectRenderers.InsertAfter<EmphasisInlineRenderer>(new SpaceNormalizerRenderer());
+}
+
+public class SpaceNormalizerParser : InlineParser
+{
+	// Collection of irregular space characters that may impair Markdown rendering
+	private static readonly char[] IrregularSpaceChars =
+	[
+		'\u000B', // Line Tabulation (\v) - <VT>
+		'\u000C', // Form Feed (\f) - <FF>
+		'\u00A0', // No-Break Space - <NBSP>
+		'\u0085', // Next Line
+		'\u1680', // Ogham Space Mark
+		'\u180E', // Mongolian Vowel Separator - <MVS>
+		'\ufeff', // Zero Width No-Break Space - <BOM>
+		'\u2000', // En Quad
+		'\u2001', // Em Quad
+		'\u2002', // En Space - <ENSP>
+		'\u2003', // Em Space - <EMSP>
+		'\u2004', // Tree-Per-Em
+		'\u2005', // Four-Per-Em
+		'\u2006', // Six-Per-Em
+		'\u2007', // Figure Space
+		'\u2008', // Punctuation Space - <PUNCSP>
+		'\u2009', // Thin Space
+		'\u200A', // Hair Space
+		'\u200B', // Zero Width Space - <ZWSP>
+		'\u2028', // Line Separator
+		'\u2029', // Paragraph Separator
+		'\u202F', // Narrow No-Break Space
+		'\u205F', // Medium Mathematical Space
+		'\u3000'  // Ideographic Space
+	];
+	private static readonly SearchValues<char> SpaceSearchValues = SearchValues.Create(IrregularSpaceChars);
+
+	// Track which files have already had the hint emitted to avoid duplicates
+	private static readonly HashSet<string> FilesWithHintEmitted = [];
+
+	public SpaceNormalizerParser() => OpeningCharacters = IrregularSpaceChars;
+
+	public override bool Match(InlineProcessor processor, ref StringSlice slice)
+	{
+		var span = slice.AsSpan().Slice(0, 1);
+		if (span.IndexOfAny(SpaceSearchValues) == -1)
+			return false;
+
+		processor.Inline = IrregularSpace.Instance;
+
+		// Emit a single hint per file on first detection
+		var context = processor.GetContext();
+		var filePath = context.MarkdownSourcePath.FullName;
+
+		lock (FilesWithHintEmitted)
+		{
+			if (!FilesWithHintEmitted.Contains(filePath))
+			{
+				_ = FilesWithHintEmitted.Add(filePath);
+				processor.EmitHint(processor.Inline, 1, "Irregular space detected. Run 'docs-builder format' to automatically fix all instances.");
+			}
+		}
+
+		slice.SkipChar();
+		return true;
+	}
+}
+
+public class IrregularSpace : LeafInline
+{
+	public static readonly IrregularSpace Instance = new();
+};
+
+public class SpaceNormalizerRenderer : HtmlObjectRenderer<IrregularSpace>
+{
+	protected override void Write(HtmlRenderer renderer, IrregularSpace obj) =>
+		renderer.Write(' ');
+}

src/Elastic.Markdown/Myst/Linters/WhiteSpaceNormalizer.cs

@@ -169,7 +169,7 @@ public static MarkdownPipeline Pipeline
 				.UseEnhancedCodeBlocks()
 				.UseHtmxLinkInlineRenderer()
 				.DisableHtml()
-				.UseWhiteSpaceNormalizer()
+				.UseSpaceNormalizer()
 				.UseHardBreaks();
 			_ = builder.BlockParsers.TryRemove<IndentedCodeBlockParser>();
 			PipelineCached = builder.Build();