Render markdown descriptions

Mpdreamz · Mpdreamz · commit 5c25c06daba6 · 2025-06-18T16:00:51.000+02:00
diff --git a/src/Elastic.ApiExplorer/ApiRenderContext.cs b/src/Elastic.ApiExplorer/ApiRenderContext.cs
@@ -2,6 +2,7 @@
 // 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 Elastic.Documentation;
 using Elastic.Documentation.Configuration;
 using Elastic.Documentation.Site.FileProviders;
 using Elastic.Documentation.Site.Navigation;
@@ -18,4 +19,5 @@ StaticFileContentHashProvider StaticFileContentHashProvider
 {
 	public required string NavigationHtml { get; init; }
 	public required INavigationItem CurrentNavigation { get; init; }
+	public required IMarkdownStringRenderer MarkdownRenderer { get; init; }
 }
diff --git a/src/Elastic.ApiExplorer/ApiViewModel.cs b/src/Elastic.ApiExplorer/ApiViewModel.cs
@@ -2,8 +2,10 @@
 // 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 Elastic.Documentation;
 using Elastic.Documentation.Site.FileProviders;
 using Elastic.Documentation.Site.Navigation;
+using Microsoft.AspNetCore.Html;
 
 namespace Elastic.ApiExplorer;
 
@@ -12,4 +14,9 @@ public abstract class ApiViewModel
 	public required string NavigationHtml { get; init; }
 	public required StaticFileContentHashProvider StaticFileContentHashProvider { get; init; }
 	public required INavigationItem CurrentNavigationItem { get; init; }
+	public required IMarkdownStringRenderer MarkdownRenderer { get; init; }
+
+
+	public HtmlString RenderMarkdown(string? markdown) =>
+		string.IsNullOrEmpty(markdown) ? new(string.Empty) : new(MarkdownRenderer.Render(markdown, null));
 }
diff --git a/src/Elastic.ApiExplorer/Endpoints/ApiEndpoint.cs b/src/Elastic.ApiExplorer/Endpoints/ApiEndpoint.cs
@@ -27,7 +27,8 @@ public async Task RenderAsync(FileSystemStream stream, ApiRenderContext context,
 			ApiEndpoint = this,
 			StaticFileContentHashProvider = context.StaticFileContentHashProvider,
 			NavigationHtml = context.NavigationHtml,
-			CurrentNavigationItem = context.CurrentNavigation
+			CurrentNavigationItem = context.CurrentNavigation,
+			MarkdownRenderer = context.MarkdownRenderer
 
 		};
 		var slice = EndpointView.Create(viewModel);
diff --git a/src/Elastic.ApiExplorer/Endpoints/IndexViewModel.cs b/src/Elastic.ApiExplorer/Endpoints/IndexViewModel.cs
@@ -3,11 +3,11 @@
 // See the LICENSE file in the project root for more information
 
 using Elastic.ApiExplorer.Landing;
+using Elastic.Documentation;
 
 namespace Elastic.ApiExplorer.Endpoints;
 
 public class IndexViewModel : ApiViewModel
 {
 	public required ApiEndpoint ApiEndpoint { get; init; }
-
 }
diff --git a/src/Elastic.ApiExplorer/Landing/LandingNavigationItem.cs b/src/Elastic.ApiExplorer/Landing/LandingNavigationItem.cs
@@ -20,7 +20,8 @@ public async Task RenderAsync(FileSystemStream stream, ApiRenderContext context,
 			StaticFileContentHashProvider = context.StaticFileContentHashProvider,
 			NavigationHtml = context.NavigationHtml,
 			ApiInfo = context.Model.Info,
-			CurrentNavigationItem = context.CurrentNavigation
+			CurrentNavigationItem = context.CurrentNavigation,
+			MarkdownRenderer = context.MarkdownRenderer
 		};
 		var slice = LandingView.Create(viewModel);
 		await slice.RenderAsync(stream, cancellationToken: ctx);
diff --git a/src/Elastic.ApiExplorer/OpenApiGenerator.cs b/src/Elastic.ApiExplorer/OpenApiGenerator.cs
@@ -5,6 +5,7 @@
 using System.IO.Abstractions;
 using Elastic.ApiExplorer.Landing;
 using Elastic.ApiExplorer.Operations;
+using Elastic.Documentation;
 using Elastic.Documentation.Configuration;
 using Elastic.Documentation.Site.FileProviders;
 using Elastic.Documentation.Site.Navigation;
@@ -37,7 +38,7 @@ public record ApiEndpoint(List<ApiOperation> Operations, string? Name) : IApiGro
 	public Task RenderAsync(FileSystemStream stream, ApiRenderContext context, CancellationToken ctx = default) => Task.CompletedTask;
 }
 
-public class OpenApiGenerator(BuildContext context, ILoggerFactory logger)
+public class OpenApiGenerator(BuildContext context, IMarkdownStringRenderer markdownStringRenderer, ILoggerFactory logger)
 {
 	private readonly ILogger _logger = logger.CreateLogger<OpenApiGenerator>();
 	private readonly IFileSystem _writeFileSystem = context.WriteFileSystem;
@@ -256,7 +257,8 @@ public async Task Generate(Cancel ctx = default)
 		var renderContext = new ApiRenderContext(context, openApiDocument, _contentHashProvider)
 		{
 			NavigationHtml = string.Empty,
-			CurrentNavigation = navigation
+			CurrentNavigation = navigation,
+			MarkdownRenderer = markdownStringRenderer
 		};
 		_ = await Render(navigation, navigation.Index, renderContext, navigationRenderer, ctx);
 		await RenderNavigationItems(navigation);
diff --git a/src/Elastic.ApiExplorer/Operations/OperationNavigationItem.cs b/src/Elastic.ApiExplorer/Operations/OperationNavigationItem.cs
@@ -21,7 +21,8 @@ public async Task RenderAsync(FileSystemStream stream, ApiRenderContext context,
 			Operation = this,
 			StaticFileContentHashProvider = context.StaticFileContentHashProvider,
 			NavigationHtml = context.NavigationHtml,
-			CurrentNavigationItem = context.CurrentNavigation
+			CurrentNavigationItem = context.CurrentNavigation,
+			MarkdownRenderer = context.MarkdownRenderer
 		};
 		var slice = OperationView.Create(viewModel);
 		await slice.RenderAsync(stream, cancellationToken: ctx);
diff --git a/src/Elastic.ApiExplorer/Operations/OperationView.cshtml b/src/Elastic.ApiExplorer/Operations/OperationView.cshtml
@@ -44,7 +44,7 @@
 <section id="elastic-api-v3">
 	<h1>@operation.Summary</h1>
 	<p>
-		@operation.Description
+		@(Model.RenderMarkdown(operation.Description))
 	</p>
 	<ul class="api-url-listing">
 		@foreach (var overload in allOperations)
@@ -64,12 +64,12 @@
 	}
 	@if (pathParameters.Length > 0)
 	{
-		<h3>Path Parameters</h3>
+		<h4>Path Parameters</h4>
 		<dl>
 		@foreach (var path in pathParameters)
 		{
 			<dt id="@path.Name"><a href="#@path.Name"><code>@path.Name</code></a></dt>
-			<dd>@path.Description</dd>
+			<dd>@Model.RenderMarkdown(path.Description)</dd>
 		}
 		</dl>
 	}
@@ -78,12 +78,25 @@
 	}
 	@if (queryStringParameters.Length > 0)
 	{
-		<h3>Query String Parameters</h3>
+		<h4>Query String Parameters</h4>
 		<dl>
 			@foreach (var path in queryStringParameters)
 			{
 				<dt id="@path.Name"><a href="#@path.Name"><code>@path.Name</code></a></dt>
-				<dd>@path.Description</dd>
+				<dd>@Model.RenderMarkdown(path.Description)</dd>
+			}
+		</dl>
+	}
+	@if (operation.RequestBody is not null)
+	{
+		<h3>Request Body</h3>
+		if (!string.IsNullOrEmpty(operation.RequestBody.Description))
+		{
+			<p>@operation.RequestBody.Description</p>
+		}
+		<dl>
+			@foreach (var path in operation.RequestBody.Content)
+			{
 			}
 		</dl>
 	}
diff --git a/src/Elastic.Documentation.Configuration/Elastic.Documentation.Configuration.csproj b/src/Elastic.Documentation.Configuration/Elastic.Documentation.Configuration.csproj
@@ -15,6 +15,5 @@
     <PackageReference Include="Samboy063.Tomlet" />
     <PackageReference Include="Vecc.YamlDotNet.Analyzers.StaticGenerator"/>
     <PackageReference Include="YamlDotNet"/>
-    <PackageReference Include="System.IO.Abstractions" />
   </ItemGroup>
 </Project>
diff --git a/src/Elastic.Documentation.Site/Assets/api-docs.css b/src/Elastic.Documentation.Site/Assets/api-docs.css
@@ -98,4 +98,7 @@
 	h3 {
 		@apply border-b-grey-20 border-b-1 pb-2;
 	}
+	h4 {
+		@apply border-b-grey-20 border-b-1 pb-2;
+	}
 }
diff --git a/src/Elastic.Documentation/IMarkdownStringRenderer.cs b/src/Elastic.Documentation/IMarkdownStringRenderer.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
+
+using System.IO.Abstractions;
+
+namespace Elastic.Documentation;
+
+public interface IMarkdownStringRenderer
+{
+	string Render(string markdown, IFileInfo? source);
+}
+public class NoopMarkdownStringRenderer : IMarkdownStringRenderer
+{
+	private NoopMarkdownStringRenderer() { }
+
+	public static NoopMarkdownStringRenderer Instance { get; } = new();
+
+	/// <inheritdoc />
+	public string Render(string markdown, IFileInfo? source) => string.Empty;
+}
diff --git a/src/Elastic.Markdown/DocumentationGenerator.cs b/src/Elastic.Markdown/DocumentationGenerator.cs
@@ -4,6 +4,7 @@
 
 using System.IO.Abstractions;
 using System.Text.Json;
+using Elastic.Documentation;
 using Elastic.Documentation.Configuration;
 using Elastic.Documentation.Legacy;
 using Elastic.Documentation.Links;
@@ -49,6 +50,7 @@ public class DocumentationGenerator
 	public DocumentationSet DocumentationSet { get; }
 	public BuildContext Context { get; }
 	public ICrossLinkResolver Resolver { get; }
+	public IMarkdownStringRenderer MarkdownStringRenderer => HtmlWriter;
 
 	public DocumentationGenerator(
 		DocumentationSet docSet,
diff --git a/src/Elastic.Markdown/Slices/HtmlWriter.cs b/src/Elastic.Markdown/Slices/HtmlWriter.cs
@@ -24,6 +24,7 @@ public class HtmlWriter(
 	ILegacyUrlMapper? legacyUrlMapper = null,
 	IPositionalNavigation? positionalNavigation = null
 )
+	: IMarkdownStringRenderer
 {
 	private DocumentationSet DocumentationSet { get; } = documentationSet;
 
@@ -34,6 +35,14 @@ public class HtmlWriter(
 	private ILegacyUrlMapper LegacyUrlMapper { get; } = legacyUrlMapper ?? new NoopLegacyUrlMapper();
 	private IPositionalNavigation PositionalNavigation { get; } = positionalNavigation ?? documentationSet;
 
+	/// <inheritdoc />
+	public string Render(string markdown, IFileInfo? source)
+	{
+		source ??= DocumentationSet.Context.ConfigurationPath;
+		var parsed = DocumentationSet.MarkdownParser.ParseStringAsync(markdown, source, null);
+		return MarkdownFile.CreateHtml(parsed);
+	}
+
 	public async Task<string> RenderLayout(MarkdownFile markdown, Cancel ctx = default)
 	{
 		var document = await markdown.ParseFullAsync(ctx);
@@ -147,4 +156,5 @@ public async Task<MarkdownDocument> WriteAsync(IFileInfo outputFile, MarkdownFil
 		await writeFileSystem.File.WriteAllTextAsync(path, rendered, ctx);
 		return document;
 	}
+
 }
diff --git a/src/tooling/docs-builder/Cli/Commands.cs b/src/tooling/docs-builder/Cli/Commands.cs
@@ -161,7 +161,8 @@ public async Task<int> Generate(
 		var generator = new DocumentationGenerator(set, logger, null, null, null, exporter);
 		_ = await generator.GenerateAll(ctx);
 
-		var openApiGenerator = new OpenApiGenerator(context, logger);
+
+		var openApiGenerator = new OpenApiGenerator(context, generator.MarkdownStringRenderer, logger);
 		await openApiGenerator.Generate(ctx);
 
 		if (runningOnCi)
diff --git a/src/tooling/docs-builder/Http/ReloadableGeneratorState.cs b/src/tooling/docs-builder/Http/ReloadableGeneratorState.cs
@@ -3,6 +3,7 @@
 // See the LICENSE file in the project root for more information
 using System.IO.Abstractions;
 using Elastic.ApiExplorer;
+using Elastic.Documentation;
 using Elastic.Documentation.Configuration;
 using Elastic.Markdown;
 using Elastic.Markdown.IO;
@@ -36,15 +37,15 @@ public async Task ReloadAsync(Cancel ctx)
 		await generator.ResolveDirectoryTree(ctx);
 		_ = Interlocked.Exchange(ref _generator, generator);
 
-		await ReloadApiReferences(ctx);
+		await ReloadApiReferences(generator.MarkdownStringRenderer, ctx);
 	}
 
-	private async Task ReloadApiReferences(Cancel ctx)
+	private async Task ReloadApiReferences(IMarkdownStringRenderer markdownStringRenderer, Cancel ctx)
 	{
 		if (ApiPath.Exists)
 			ApiPath.Delete(true);
 		ApiPath.Create();
-		var generator = new OpenApiGenerator(context, logger);
+		var generator = new OpenApiGenerator(context, markdownStringRenderer, logger);
 		await generator.Generate(ctx);
 	}
 }
diff --git a/tests/Elastic.ApiExplorer.Tests/ReaderTests.cs b/tests/Elastic.ApiExplorer.Tests/ReaderTests.cs
@@ -3,6 +3,7 @@
 // See the LICENSE file in the project root for more information
 
 using System.IO.Abstractions;
+using Elastic.Documentation;
 using Elastic.Documentation.Configuration;
 using Elastic.Documentation.Diagnostics;
 using FluentAssertions;
@@ -32,7 +33,7 @@ public async Task Navigation()
 	{
 		var collector = new DiagnosticsCollector([]);
 		var context = new BuildContext(collector, new FileSystem());
-		var generator = new OpenApiGenerator(context, NullLoggerFactory.Instance);
+		var generator = new OpenApiGenerator(context, NoopMarkdownStringRenderer.Instance, NullLoggerFactory.Instance);
 		context.Configuration.OpenApiSpecification.Should().NotBeNull();
 
 		var openApiDocument = await OpenApiReader.Create(context.Configuration.OpenApiSpecification);

Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@`
`2`	`2`	`// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.`
`3`	`3`	`// See the LICENSE file in the project root for more information`
`4`	`4`
	`5`	`+using Elastic.Documentation;`
`5`	`6`	`using Elastic.Documentation.Configuration;`
`6`	`7`	`using Elastic.Documentation.Site.FileProviders;`
`7`	`8`	`using Elastic.Documentation.Site.Navigation;`
`@@ -18,4 +19,5 @@ StaticFileContentHashProvider StaticFileContentHashProvider`
`18`	`19`	`{`
`19`	`20`	`public required string NavigationHtml { get; init; }`
`20`	`21`	`public required INavigationItem CurrentNavigation { get; init; }`
	`22`	`+ public required IMarkdownStringRenderer MarkdownRenderer { get; init; }`
`21`	`23`	`}`
Original file line number	Diff line number	Diff line change
`@@ -3,11 +3,11 @@`
`3`	`3`	`// See the LICENSE file in the project root for more information`
`4`	`4`
`5`	`5`	`using Elastic.ApiExplorer.Landing;`
	`6`	`+using Elastic.Documentation;`
`6`	`7`
`7`	`8`	`namespace Elastic.ApiExplorer.Endpoints;`
`8`	`9`
`9`	`10`	`public class IndexViewModel : ApiViewModel`
`10`	`11`	`{`
`11`	`12`	`public required ApiEndpoint ApiEndpoint { get; init; }`
`12`		`-`
`13`	`13`	`}`
Original file line number	Diff line number	Diff line change
`@@ -44,7 +44,7 @@`
`44`	`44`	`<section id="elastic-api-v3">`
`45`	`45`	`<h1>@operation.Summary</h1>`
`46`	`46`	`<p>`
`47`		`- @operation.Description`
	`47`	`+ @(Model.RenderMarkdown(operation.Description))`
`48`	`48`	`</p>`
`49`	`49`	`<ul class="api-url-listing">`
`50`	`50`	`@foreach (var overload in allOperations)`
`@@ -64,12 +64,12 @@`
`64`	`64`	`}`
`65`	`65`	`@if (pathParameters.Length > 0)`
`66`	`66`	`{`
`67`		`- <h3>Path Parameters</h3>`
	`67`	`+ <h4>Path Parameters</h4>`
`68`	`68`	`<dl>`
`69`	`69`	`@foreach (var path in pathParameters)`
`70`	`70`	`{`
`71`	`71`	`<dt id="@path.Name"><a href="#@path.Name"><code>@path.Name</code></a></dt>`
`72`		`- <dd>@path.Description</dd>`
	`72`	`+ <dd>@Model.RenderMarkdown(path.Description)</dd>`
`73`	`73`	`}`
`74`	`74`	`</dl>`
`75`	`75`	`}`
`@@ -78,12 +78,25 @@`
`78`	`78`	`}`
`79`	`79`	`@if (queryStringParameters.Length > 0)`
`80`	`80`	`{`
`81`		`- <h3>Query String Parameters</h3>`
	`81`	`+ <h4>Query String Parameters</h4>`
`82`	`82`	`<dl>`
`83`	`83`	`@foreach (var path in queryStringParameters)`
`84`	`84`	`{`
`85`	`85`	`<dt id="@path.Name"><a href="#@path.Name"><code>@path.Name</code></a></dt>`
`86`		`- <dd>@path.Description</dd>`
	`86`	`+ <dd>@Model.RenderMarkdown(path.Description)</dd>`
	`87`	`+ }`
	`88`	`+ </dl>`
	`89`	`+ }`
	`90`	`+ @if (operation.RequestBody is not null)`
	`91`	`+ {`
	`92`	`+ <h3>Request Body</h3>`
	`93`	`+ if (!string.IsNullOrEmpty(operation.RequestBody.Description))`
	`94`	`+ {`
	`95`	`+ <p>@operation.RequestBody.Description</p>`
	`96`	`+ }`
	`97`	`+ <dl>`
	`98`	`+ @foreach (var path in operation.RequestBody.Content)`
	`99`	`+ {`
`87`	`100`	`}`
`88`	`101`	`</dl>`
`89`	`102`	`}`
Original file line number	Diff line number	Diff line change
`@@ -98,4 +98,7 @@`
`98`	`98`	`h3 {`
`99`	`99`	`@apply border-b-grey-20 border-b-1 pb-2;`
`100`	`100`	`}`
	`101`	`+ h4 {`
	`102`	`+ @apply border-b-grey-20 border-b-1 pb-2;`
	`103`	`+ }`
`101`	`104`	`}`