Fix various issues

Author: theletterf

docs/_docset.yml

@@ -86,7 +86,7 @@ toc:
       - file: code.md
       - file: comments.md
       - file: conditionals.md
-      - hidden: diagrams.md
+      - file: diagrams.md
       - file: dropdowns.md
       - file: definition-lists.md
       - file: example_blocks.md

docs/syntax/diagrams.md

@@ -84,7 +84,7 @@ sequenceDiagram
 :::::{tab-item} Rendered
 ::::{diagram} mermaid
 sequenceDiagram
-    participant A as Alice
+    participant A as Ada
     participant B as Bob
     A->>B: Hello Bob, how are you?
     B-->>A: Great!

src/Elastic.Markdown/Myst/Directives/Diagram/DiagramBlock.cs

@@ -71,7 +71,8 @@ public override void FinalizeAndValidate(ParserContext context)
 		// Register diagram for tracking and cleanup
 		DiagramRegistry.RegisterDiagram(LocalSvgPath);
 
-		// Cache diagram asynchronously
+		// Cache diagram asynchronously - fire and forget
+		// Use simplified approach without lock files to avoid orphaned locks
 		_ = Task.Run(() => TryCacheDiagramAsync(context));
 	}
 
@@ -125,7 +126,7 @@ private async Task TryCacheDiagramAsync(ParserContext context)
 			var outputDirectory = context.Build.DocumentationOutputDirectory.FullName;
 			var fullPath = Path.Combine(outputDirectory, LocalSvgPath);
 
-			// Skip if file already exists
+			// Skip if file already exists - simple check without locking
 			if (File.Exists(fullPath))
 				return;
 
@@ -136,17 +137,41 @@ private async Task TryCacheDiagramAsync(ParserContext context)
 				_ = Directory.CreateDirectory(directory);
 			}
 
-			// Download SVG from Kroki
-			using var httpClient = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
-			var svgContent = await httpClient.GetStringAsync(EncodedUrl);
+			// Download SVG from Kroki using shared HttpClient
+			var svgContent = await DiagramHttpClient.Instance.GetStringAsync(EncodedUrl);
 
-			// Write to local file
-			await File.WriteAllTextAsync(fullPath, svgContent);
+			// Basic validation - ensure we got SVG content
+			// SVG can start with XML declaration, DOCTYPE, or directly with <svg>
+			if (string.IsNullOrWhiteSpace(svgContent) || !svgContent.Contains("<svg", StringComparison.OrdinalIgnoreCase))
+			{
+				// Invalid content - don't cache
+				return;
+			}
+
+			// Write to local file atomically using a temp file
+			var tempPath = fullPath + ".tmp";
+			await File.WriteAllTextAsync(tempPath, svgContent);
+			File.Move(tempPath, fullPath);
+		}
+		catch (HttpRequestException)
+		{
+			// Network-related failures - silent fallback to Kroki URLs
+			// Caching is opportunistic, network issues shouldn't generate warnings
+		}
+		catch (TaskCanceledException ex) when (ex.InnerException is TimeoutException)
+		{
+			// Timeout - silent fallback to Kroki URLs
+			// Timeouts are expected in slow network conditions
+		}
+		catch (IOException)
+		{
+			// File system issues - silent fallback to Kroki URLs
+			// Disk space or permission issues shouldn't break builds
 		}
-		catch
+		catch (Exception)
 		{
-			// Silent failure - caching is opportunistic
-			// The system will fall back to Kroki URLs
+			// Unexpected errors - silent fallback to Kroki URLs
+			// Caching is opportunistic, any failure should fallback gracefully
 		}
 	}
 }

src/Elastic.Markdown/Myst/Directives/Diagram/DiagramHttpClient.cs

@@ -0,0 +1,21 @@
+// 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
+
+namespace Elastic.Markdown.Myst.Directives.Diagram;
+
+/// <summary>
+/// Shared HttpClient for diagram downloads to avoid resource exhaustion
+/// </summary>
+public static class DiagramHttpClient
+{
+	private static readonly Lazy<HttpClient> LazyHttpClient = new(() => new HttpClient
+	{
+		Timeout = TimeSpan.FromSeconds(30)
+	});
+
+	/// <summary>
+	/// Shared HttpClient instance for diagram downloads
+	/// </summary>
+	public static HttpClient Instance => LazyHttpClient.Value;
+}

src/Elastic.Markdown/Myst/Directives/Diagram/DiagramView.cshtml

@@ -6,7 +6,7 @@
 		<div class="diagram" data-diagram-type="@diagram.DiagramType">
 			@if (!string.IsNullOrEmpty(diagram.LocalSvgPath))
 			{
-				<img src="@diagram.LocalSvgPath" 
+				<img src="/@diagram.LocalSvgPath" 
 				     alt="@diagram.DiagramType diagram" 
 				     loading="lazy"
 				     onerror="this.src='@diagram.EncodedUrl'" />

src/tooling/docs-builder/Http/DocumentationWebHost.cs

@@ -18,6 +18,7 @@
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.AspNetCore.Http;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.FileProviders;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging;
 using Westwind.AspNetCore.LiveReload;
@@ -152,6 +153,12 @@ await context.Response.WriteAsync(@"
 					FileProvider = new EmbeddedOrPhysicalFileProvider(Context),
 					RequestPath = "/_static"
 				})
+			.UseStaticFiles(
+				new StaticFileOptions
+				{
+					FileProvider = new PhysicalFileProvider(Context.DocumentationOutputDirectory.FullName),
+					RequestPath = ""
+				})
 			.UseRouting();
 
 		_ = _webApplication.MapGet("/", (ReloadableGeneratorState holder, Cancel ctx) =>