Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix inline code in left navigation and h1 rendering #290

Open
wants to merge 14 commits into
base: main
Choose a base branch
from
+35 −4
Open

Fix inline code in left navigation and h1 rendering #290

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
deeb33a
Fix inline code in left navigation and h1 rendering
reakaleek Jan 22, 2025
921f8ea
Format and license
reakaleek Jan 22, 2025
19327bf
Revert locally.md
reakaleek Jan 22, 2025
97f4c94
fix
reakaleek Jan 22, 2025
5e07657
Add comment
reakaleek Jan 22, 2025
15ee32d
Refactor and use Markdig to strip markdown
reakaleek Jan 23, 2025
101b0be
Trim result because it sometimes has a newline
reakaleek Jan 23, 2025
226d834
Remove obvious comment
reakaleek Jan 23, 2025
3c46f20
Unnecessary check
reakaleek Jan 23, 2025
2b4e21d
Set once
reakaleek Jan 23, 2025
4ddc4bb
Use extension method
reakaleek Jan 23, 2025
e00d555
Add TitleRaw property
reakaleek Jan 23, 2025
9131b38
Revert req.md
reakaleek Jan 23, 2025
910bb55
Merge branch 'main' into feature/fix-inline-code-in-left-navigation
reakaleek Jan 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions src/Elastic.Markdown/Helpers/Markdown.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
// 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.Helpers;

public static class Markdown
{
public static string StripMarkdown(string markdown)
Copy link
Member

@Mpdreamz Mpdreamz Jan 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm partial to making these extension methods.

Suggested change
public static class Markdown
{
public static string StripMarkdown(string markdown)
public static string class MarkdownStringExtensions
{
public static string StripMarkdown(this string markdown)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

4ddc4bb

{
using var writer = new StringWriter();
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For funsies tried to see if pooling the StringBuilder() this instantatiates each time had an impact but its very minimal:

private static readonly ObjectPool<StringBuilder> StringBuilderPool = new DefaultObjectPool<StringBuilder>(new StringBuilderPooledObjectPolicy());
public static string StripMarkdownPooled(string markdown)
{
   	var sb = StringBuilderPool.Get();
	try
	{
		using var writer = new StringWriter(sb, CultureInfo.InvariantCulture);
		Markdig.Markdown.ToPlainText(markdown, writer);
		return writer.ToString().TrimEnd('\n');
	}
	finally
	{
		StringBuilderPool.Return(sb);
	}
}
Method Mean Error Gen0 Gen1 Allocated
StripMarkdown 1.963 us NA 0.4829 0.0029 3.95 KB
StripMarkdownPooled 1.706 us NA 0.4435 0.0027 3.63 KB

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh interesting, thank you!

How did you actually measure this?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Benchmark dot Will add a general benchmarking project at some point in the next week so we can utilize this more.

and: https://www.elastic.co/guide/en/ecs-logging/dotnet/current/benchmark-dotnet-data-shipper.html on CI 😄

Markdig.Markdown.ToPlainText(markdown, writer);
return writer.ToString().TrimEnd('\n');
}
}
8 changes: 6 additions & 2 deletions src/Elastic.Markdown/IO/MarkdownFile.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,11 @@ public DocumentationGroup? Parent
public string? Title { get; private set; }
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe introduce a TitleRaw property thats the markdown so that we can assume Title and NavigationTitle are sanitized.

Then when rendering we can use TitleRaw

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

7bb6322

Copy link
Member Author

@reakaleek reakaleek Jan 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm a bit unsure about this. This caused changes in various places, where it's not entirely clear to me if it expects a raw markdown string or sanitized title.

Was the assumption that it's only a sanitized title during the first implementations?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See my comment here: https://github.com/elastic/docs-builder/pull/290/files#r1927019403

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

e00d555

public string? NavigationTitle
{
get => !string.IsNullOrEmpty(_navigationTitle) ? _navigationTitle : Title;
get
{
var title = !string.IsNullOrEmpty(_navigationTitle) ? _navigationTitle : Title;
return string.IsNullOrEmpty(title) ? null : Helpers.Markdown.StripMarkdown(title);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
return string.IsNullOrEmpty(title) ? null : Helpers.Markdown.StripMarkdown(title);
return string.IsNullOrEmpty(title) ? null : title.StripMarkdown();

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

4ddc4bb

}
private set => _navigationTitle = value;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Strip once when setting instead of each time we get the property.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

7bb6322

}

Expand Down Expand Up @@ -159,7 +163,7 @@ private void ReadDocumentInstructions(MarkdownDocument document)
.Select(h => (h.GetData("header") as string, h.GetData("anchor") as string))
.Select(h => new PageTocItem
{
Heading = h.Item1!.Replace("`", "").Replace("*", ""),
Heading = Helpers.Markdown.StripMarkdown(h.Item1!),
Slug = _slugHelper.GenerateSlug(h.Item2 ?? h.Item1)
})
.ToList();
Expand Down
4 changes: 3 additions & 1 deletion src/Elastic.Markdown/Slices/Index.cshtml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
@using Markdig
@inherits RazorSliceHttpResult<IndexViewModel>
@implements IUsesLayout<Elastic.Markdown.Slices._Layout, LayoutViewModel>
@functions {
Expand All @@ -16,7 +17,8 @@
};
}
<section id="elastic-docs-v3">
<h1>@(Model.Title)</h1>
@* This way it's correctly rendered as <h1>text</h1> instead of <h1><p>text</p></h1> *@
@(new HtmlString(Markdown.ToHtml("# " + Model.Title)))
@if (Model.Applies is not null)
{
await RenderPartialAsync(Applies.Create(Model.Applies));
Expand Down
Loading