");
_ = renderer.Write("
");
- _ = renderer.Write("
");
- _ = renderer.Write(svg);
+ _ = renderer.Write($"
");
+ _ = renderer.Write($"
![\"Mermaid](\"{svgFileName}\")
");
_ = renderer.Write("
");
}
+ ///
+ /// Writes the SVG to a file next to the page's output HTML and returns the filename.
+ /// The filename is a content hash so identical diagrams on multiple pages share one file.
+ ///
+ private static string WriteSvgFile(EnhancedCodeBlock block, string svg)
+ {
+ var hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(svg)))[..8].ToLowerInvariant();
+ var stem = Path.GetFileNameWithoutExtension(block.CurrentFile.Name);
+ var svgFileName = $"{stem}-{hash}.svg";
+
+ // Mirror HtmlWriter.WriteAsync path logic to find the output directory for this page.
+ var sourceRoot = block.Build.DocumentationSourceDirectory.FullName;
+ var relPath = Path.GetRelativePath(sourceRoot, block.CurrentFile.FullName);
+ var outputSubdir = Path.GetFileName(relPath) == "index.md"
+ ? Path.GetDirectoryName(relPath) ?? "."
+ : Path.Combine(Path.GetDirectoryName(relPath) ?? ".", Path.GetFileNameWithoutExtension(relPath));
+
+ var svgPath = Path.Combine(block.Build.OutputDirectory.FullName, outputSubdir, svgFileName);
+ var svgFile = block.Build.WriteFileSystem.FileInfo.New(svgPath);
+
+ if (!svgFile.Exists)
+ {
+ svgFile.Directory?.Create();
+ block.Build.WriteFileSystem.File.WriteAllText(svgPath, svg);
+ }
+
+ // Use an absolute URL so the src resolves correctly regardless of whether the
+ // browser's current URL has a trailing slash (no-slash: relative would resolve
+ // one level too high and miss the page subdirectory).
+ var urlSubdir = outputSubdir.Replace(Path.DirectorySeparatorChar, '/').Trim('.');
+ return $"{block.Build.UrlPathPrefix}/{urlSubdir}/{svgFileName}".Replace("//", "/");
+ }
+
private static string ExtractMermaidText(EnhancedCodeBlock block)
{
var commonIndent = GetCommonIndent(block);
diff --git a/src/tooling/docs-builder/Http/DocumentationWebHost.cs b/src/tooling/docs-builder/Http/DocumentationWebHost.cs
index f8922fa23..8ef88049c 100644
--- a/src/tooling/docs-builder/Http/DocumentationWebHost.cs
+++ b/src/tooling/docs-builder/Http/DocumentationWebHost.cs
@@ -161,7 +161,7 @@ private void SetUpRoutes()
.UseRouting();
_ = _webApplication.MapGet("/", (ReloadableGeneratorState holder, Cancel ctx) =>
- ServeDocumentationFile(holder, "index", ctx));
+ ServeDocumentationFile(holder, "index", _writeFileSystem, ctx));
_ = _webApplication.MapGet("/api/", (ReloadableGeneratorState holder, Cancel ctx) =>
ServeApiFile(holder, "", ctx));
@@ -212,7 +212,7 @@ private void SetUpRoutes()
Results.Json(buildState.GetCurrentState(), DiagnosticsJsonContext.Default.BuildEvent));
_ = _webApplication.MapGet("{**slug}", (string slug, ReloadableGeneratorState holder, Cancel ctx) =>
- ServeDocumentationFile(holder, slug, ctx));
+ ServeDocumentationFile(holder, slug, _writeFileSystem, ctx));
}
private static async Task WriteSSEEvent(HttpResponse response, string eventType, BuildEvent data, Cancel ct)
@@ -255,7 +255,7 @@ private async Task
ServeApiFile(ReloadableGeneratorState holder, string
return Results.NotFound();
}
- private static async Task ServeDocumentationFile(ReloadableGeneratorState holder, string slug, Cancel ctx)
+ private static async Task ServeDocumentationFile(ReloadableGeneratorState holder, string slug, ScopedFileSystem writeFs, Cancel ctx)
{
if (slug == ".well-known/appspecific/com.chrome.devtools.json")
return Results.NotFound();
@@ -310,6 +310,29 @@ private static async Task ServeDocumentationFile(ReloadableGeneratorSta
if (s == "index.md")
return Results.Redirect(generator.DocumentationSet.Navigation.Url);
+ // Serve static output assets (e.g. Mermaid SVG files written alongside HTML).
+ var ext = Path.GetExtension(slug);
+ if (ext is ".svg" or ".png" or ".jpg" or ".jpeg" or ".gif" or ".ico" or ".webp")
+ {
+ var outputPath = Path.Combine(generator.DocumentationSet.Context.OutputDirectory.FullName, slug);
+ var outputFile = writeFs.FileInfo.New(outputPath);
+ if (outputFile.Exists)
+ {
+ var mimeType = ext switch
+ {
+ ".svg" => "image/svg+xml",
+ ".png" => "image/png",
+ ".jpg" or ".jpeg" => "image/jpeg",
+ ".gif" => "image/gif",
+ ".ico" => "image/x-icon",
+ ".webp" => "image/webp",
+ _ => "application/octet-stream"
+ };
+ var bytes = await writeFs.File.ReadAllBytesAsync(outputPath, ctx);
+ return Results.Bytes(bytes, mimeType);
+ }
+ }
+
var fp404 = new FilePath("404.md", generator.DocumentationSet.SourceDirectory);
if (!generator.DocumentationSet.Files.TryGetValue(fp404, out var notFoundDocumentationFile))
return Results.NotFound();
diff --git a/tests/Elastic.Markdown.Tests/Directives/DirectiveBaseTests.cs b/tests/Elastic.Markdown.Tests/Directives/DirectiveBaseTests.cs
index 631d450c8..28c57c3d8 100644
--- a/tests/Elastic.Markdown.Tests/Directives/DirectiveBaseTests.cs
+++ b/tests/Elastic.Markdown.Tests/Directives/DirectiveBaseTests.cs
@@ -119,6 +119,19 @@ public virtual async ValueTask InitializeAsync()
await Collector.StopAsync(TestContext.Current.CancellationToken);
}
+ ///
+ /// Returns the content of all SVG files written to the output directory during rendering.
+ /// Use this to assert on diagram content after the switch from inline SVG to external files.
+ ///
+ protected IReadOnlyList ReadMermaidSvgs()
+ {
+ var outputDir = Set.Context.OutputDirectory.FullName;
+ return FileSystem.AllFiles
+ .Where(f => f.StartsWith(outputDir, StringComparison.OrdinalIgnoreCase) && f.EndsWith(".svg", StringComparison.OrdinalIgnoreCase))
+ .Select(f => FileSystem.File.ReadAllText(f))
+ .ToList();
+ }
+
public ValueTask DisposeAsync()
{
GC.SuppressFinalize(this);
diff --git a/tests/Elastic.Markdown.Tests/Directives/MermaidTests.cs b/tests/Elastic.Markdown.Tests/Directives/MermaidTests.cs
index 3a8dfc240..f14139014 100644
--- a/tests/Elastic.Markdown.Tests/Directives/MermaidTests.cs
+++ b/tests/Elastic.Markdown.Tests/Directives/MermaidTests.cs
@@ -30,14 +30,18 @@ flowchart LR
public void RendersMermaidContainer() => Html.Should().Contain("");
[Fact]
- public void RendersInlineSvg() => Html.Should().Contain("
Html.Should().Contain(" ReadMermaidSvgs().Should().NotBeEmpty();
+
+ [Fact]
+ public void SvgContainsNodeLabels()
{
- Html.Should().Contain("Start");
- Html.Should().Contain("Process");
- Html.Should().Contain("End");
+ var svg = ReadMermaidSvgs()[0];
+ svg.Should().Contain("Start");
+ svg.Should().Contain("Process");
+ svg.Should().Contain("End");
}
}
@@ -62,13 +66,14 @@ participant B as Bob
public void RendersMermaidContainer() => Html.Should().Contain("");
[Fact]
- public void RendersInlineSvg() => Html.Should().Contain("
Html.Should().Contain(" Html.Should().Contain("");
[Fact]
- public void RendersInlineSvg() => Html.Should().Contain("
Html.Should().Contain(" Html.Should().Contain("");
[Fact]
- public void RendersInlineSvg() => Html.Should().Contain("
Html.Should().Contain(" Html.Should().Contain("");
[Fact]
- public void RendersInlineSvg() => Html.Should().Contain("
Html.Should().Contain(" Collector.Diagnostics.Should().NotBeEmpty();
[Fact]
- public void RendersAsSvg() => Html.Should().Contain(" ReadMermaidSvgs().Should().NotBeEmpty();
[Fact]
public void DoesNotFallBackToRawSource() => Html.Should().NotContain("");
@@ -203,13 +211,13 @@ flowchart LR
public void RendersMermaidContainer() => Html.Should().Contain("");
[Fact]
- public void RendersInlineSvg() => Html.Should().Contain("
Html.Should().Contain(" Collector.Diagnostics.Should().BeEmpty();
[Fact]
- public void SvgContainsWarningFillColor() => Html.Should().Contain("#fdf3d8");
+ public void SvgContainsWarningFillColor() => ReadMermaidSvgs()[0].Should().Contain("#fdf3d8");
}
// DataPalette: pie chart SVG should use our theme palette, not the Tableau CB10 default.
@@ -225,14 +233,14 @@ public class MermaidPieDataPaletteTests(ITestOutputHelper output) : DirectiveTes
)
{
[Fact]
- public void RendersInlineSvg() => Html.Should().Contain(" Html.Should().Contain(" Collector.Diagnostics.Should().BeEmpty();
[Fact]
- public void UsesThemePalette() => Html.Should().Contain("#3788ff"); // blue-elastic-70
+ public void UsesThemePalette() => ReadMermaidSvgs()[0].Should().Contain("#3788ff"); // blue-elastic-70
[Fact]
- public void DoesNotUseTableauDefault() => Html.Should().NotContain("#4e79a7"); // Tableau Blue
+ public void DoesNotUseTableauDefault() => ReadMermaidSvgs()[0].Should().NotContain("#4e79a7"); // Tableau Blue
}