"Enforce strict mode in docs builder and refine title handling"

Added the `--strict` flag to the docs builder for stricter validation. Refactored title handling logic to delay fallback to filename when no title is found. Minor fixes in generated link text in docs for better clarity.

Author: Mpdreamz

.github/workflows/pr.yml

@@ -36,4 +36,4 @@ jobs:
       # we run our artifact directly please use the prebuild
       # elastic/docs-builder@main GitHub Action for all other repositories!
       - name: Build documentation
-        run: .artifacts/publish/docs-builder/release/docs-builder
+        run: .artifacts/publish/docs-builder/release/docs-builder --strict

docs/source/syntax/titles.md

@@ -23,7 +23,7 @@ As well as when using the autolink naming feature e.g:
 [titles.md]()
 ```
 
-Generated link text: [](syntax/titles.md)
+Generated link text: [](titles.md)
 
 
 

src/Elastic.Markdown/IO/MarkdownFile.cs

@@ -100,12 +100,6 @@ private void ReadDocumentInstructions(MarkdownDocument document)
 			.FirstOrDefault(block => block is HeadingBlock { Level: 1 })?
 			.GetData("header") as string;
 
-		if (string.IsNullOrEmpty(Title))
-		{
-			Title = RelativePath;
-			Collector.EmitWarning(FilePath, "Document has no title, using file name as title.");
-		}
-
 		if (document.FirstOrDefault() is YamlFrontMatterBlock yaml)
 		{
 			var raw = string.Join(Environment.NewLine, yaml.Lines.Lines);
@@ -114,7 +108,13 @@ private void ReadDocumentInstructions(MarkdownDocument document)
 			// TODO remove when migration tool and our demo content sets are updated
 			var deprecatedTitle = YamlFrontMatter.Title;
 			if (!string.IsNullOrEmpty(deprecatedTitle))
+			{
 				Collector.EmitWarning(FilePath, "'title' is no longer supported in yaml frontmatter please use a level 1 header instead.");
+				// TODO remove fallback once migration is over and we fully deprecate front matter titles
+				if (string.IsNullOrEmpty(Title))
+					Title = deprecatedTitle;
+			}
+
 
 			// set title on yaml front matter manually.
 			// frontmatter gets passed around as page information throughout
@@ -143,6 +143,13 @@ private void ReadDocumentInstructions(MarkdownDocument document)
 		else
 			YamlFrontMatter = new YamlFrontMatter { Title = Title };
 
+		if (string.IsNullOrEmpty(Title))
+		{
+			Title = RelativePath;
+			Collector.EmitWarning(FilePath, "Document has no title, using file name as title.");
+		}
+
+
 
 		var contents = document
 			.Where(block => block is HeadingBlock { Level: >= 2 })