Fix Markdown.Normalize for custom containers and footnotes

* Write custom containers between ::: fences of their original length,
  with their info and arguments, and close an unclosed container
* Write footnote references as [^label] and footnotes as
  [^label]: content with continuation lines indented by four spaces,
  leaving out the back links and the paragraph the parser adds for them
* Skip link reference definitions that create their own inline, such as
  those of footnotes and auto-identifier headings, which wrote [^1]: and
  []: lines once a footnote put the definition group into the document
* End the definition group with a blank line, so that a following
  footnote or line is not read back as part of a definition

Co-authored-by: CodeAlta <noreply@codealta.io>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Alexandre Mutel
2026-11-04 21:35:14 +01:00
parent 58d9752a6e
commit 8b4ffd59be
9 changed files with 269 additions and 5 deletions

View File

@@ -23,6 +23,16 @@ space-after-quote option, rather than dropping the list item. Empty list items
also retain a trailing space after their marker; normalization is not an exact
whitespace round-trip.
With the custom containers extension, a container is written between `:::` fences
of its original length, with its info and arguments; a container without a closing
fence gets one. With the footnotes extension, references are written as `[^label]`
and footnotes as `[^label]: content`, with continuation lines indented by four
spaces. The parser moves footnotes to the end of the document in the order of their
first reference and drops footnotes without references, so normalized footnotes
follow that order. Link reference definitions that an extension creates, such as
those of footnotes or of headings with auto-identifiers, are not written as
`[label]: url` lines.
Custom text renderers can use `PushHangingIndent(marker)` to emit a marker on the
first line and an equal number of spaces on continuation lines. Call it at the
beginning of a line (use `EnsureLine()` if needed), before writing child content,

View File

@@ -120,6 +120,54 @@ public class TestNormalize
Assert.AreEqual("# Test\n\n## Test", writer.ToString());
}
[TestCase("[foo]: /url\n\n# Foo\n\n[foo] [Foo]", "[foo]: /url\n\n# Foo\n\n[foo] [Foo]")]
[TestCase("# Foo\n\n[Foo] [foo]\n\n[foo]: /url", "# Foo\n\n[Foo] [foo]\n\n[foo]: /url")]
public void AutoIdentifiersDoNotEmitGeneratedLinkReferenceDefinitionsBesideParsedOnes(string input, string expected)
{
AssertNormalizeKeepsHtml(input, expected, new MarkdownPipelineBuilder().UseAutoIdentifiers().Build());
}
[TestCase("::: note\nHello\n:::\n\n# Foo", "::: note\nHello\n:::\n\n# Foo")]
[TestCase(":::\n:::", ":::\n:::")]
[TestCase("::: note\nHello", "::: note\nHello\n:::")]
[TestCase(":::: outer arg1 arg2\n::: inner\nText ::inline::\n:::\n::::", ":::: outer arg1 arg2\n::: inner\nText ::inline::\n:::\n::::")]
[TestCase("- item\n\n ::: note\n > quote\n :::\n- next", "- item\n \n ::: note\n > quote\n :::\n\n- next")]
public void CustomContainer(string input, string expected)
{
AssertNormalizeKeepsHtml(input, expected, new MarkdownPipelineBuilder().UseCustomContainers().Build());
}
[TestCase("Text[^1]\n\n[^1]: Hello\n\n# Foo", "Text[^1]\n\n# Foo\n\n[^1]: Hello")]
[TestCase(
"A[^a] B[^b] A again[^a]\n\n[^b]: Second\n\n with more\n\n[^a]: First\n\n ```\n code\n ```\n\n[^unused]: Unused",
"A[^a] B[^b] A again[^a]\n\n[^a]: First\n \n ```\n code\n ```\n\n[^b]: Second\n \n with more")]
[TestCase("Text[^1]\n\n[^1]: - item", "Text[^1]\n\n[^1]: \n - item")]
[TestCase("[foo]: /url\n\nSee [foo] and[^1].\n\n[^1]: Note", "[foo]: /url\n\nSee [foo] and[^1].\n\n[^1]: Note")]
public void Footnotes(string input, string expected)
{
AssertNormalizeKeepsHtml(input, expected, new MarkdownPipelineBuilder().UseFootnotes().Build());
}
[TestCase("::: note\nHello\n:::\n\n# Foo")]
[TestCase("Text[^1]\n\n[^1]: Hello\n\n# Foo")]
[TestCase("[foo]: /url\n\n# Foo\n\n::: note\nSee [foo], [Foo] and[^1].\n:::\n\n[^1]: Note")]
public void AdvancedExtensionsKeepHtml(string input)
{
AssertNormalizeKeepsHtml(input, null, new MarkdownPipelineBuilder().UseAdvancedExtensions().Build());
}
private static void AssertNormalizeKeepsHtml(string input, string expected, MarkdownPipeline pipeline)
{
string normalized = Markdown.Normalize(input, pipeline: pipeline);
if (expected is not null)
{
Assert.AreEqual(expected, normalized);
}
Assert.AreEqual(Markdown.ToHtml(input, pipeline), Markdown.ToHtml(normalized, pipeline));
Assert.AreEqual(normalized, Markdown.Normalize(normalized, pipeline: pipeline));
}
[Test]
public void Backslash()
{

View File

@@ -4,6 +4,7 @@
using Markdig.Parsers.Inlines;
using Markdig.Renderers;
using Markdig.Renderers.Normalize;
namespace Markdig.Extensions.CustomContainers;
@@ -63,5 +64,10 @@ public class CustomContainerExtension : IMarkdownExtension
}
}
if (renderer is NormalizeRenderer normalizeRenderer)
{
normalizeRenderer.ObjectRenderers.AddIfNotAlready<NormalizeCustomContainerRenderer>();
}
}
}

View File

@@ -0,0 +1,42 @@
// Copyright (c) Alexandre Mutel. All rights reserved.
// This file is licensed under the BSD-Clause 2 license.
// See the license.txt file in the project root for more information.
using Markdig.Renderers.Normalize;
namespace Markdig.Extensions.CustomContainers;
/// <summary>
/// A Normalize renderer for a <see cref="CustomContainer"/>. It writes the content between an opening fence with the info and arguments and a closing fence of the same length.
/// </summary>
/// <seealso cref="NormalizeObjectRenderer{CustomContainer}" />
public class NormalizeCustomContainerRenderer : NormalizeObjectRenderer<CustomContainer>
{
/// <summary>
/// Writes the object to the specified renderer.
/// </summary>
protected override void Write(NormalizeRenderer renderer, CustomContainer obj)
{
char fencedChar = obj.FencedChar == '\0' ? ':' : obj.FencedChar;
int fencedCharCount = Math.Max(obj.OpeningFencedCharCount, 3);
renderer.EnsureLine();
renderer.Write(fencedChar, fencedCharCount);
if (!string.IsNullOrEmpty(obj.Info))
{
renderer.Write(' ').Write(obj.Info);
}
if (!string.IsNullOrEmpty(obj.Arguments))
{
renderer.Write(' ').Write(obj.Arguments);
}
renderer.WriteLine();
renderer.WriteChildren(obj);
// The closing fence is written even if the source had none, so that the content ends where the container ends
renderer.EnsureLine();
renderer.Write(fencedChar, fencedCharCount);
renderer.FinishBlock(true);
}
}

View File

@@ -3,6 +3,7 @@
// See the license.txt file in the project root for more information.
using Markdig.Renderers;
using Markdig.Renderers.Normalize;
namespace Markdig.Extensions.Footnotes;
@@ -34,5 +35,11 @@ public class FootnoteExtension : IMarkdownExtension
htmlRenderer.ObjectRenderers.AddIfNotAlready(new HtmlFootnoteGroupRenderer());
htmlRenderer.ObjectRenderers.AddIfNotAlready(new HtmlFootnoteLinkRenderer());
}
if (renderer is NormalizeRenderer normalizeRenderer)
{
normalizeRenderer.ObjectRenderers.AddIfNotAlready<NormalizeFootnoteGroupRenderer>();
normalizeRenderer.ObjectRenderers.AddIfNotAlready<NormalizeFootnoteLinkRenderer>();
}
}
}

View File

@@ -0,0 +1,95 @@
// Copyright (c) Alexandre Mutel. All rights reserved.
// This file is licensed under the BSD-Clause 2 license.
// See the license.txt file in the project root for more information.
using Markdig.Renderers.Normalize;
using Markdig.Syntax;
namespace Markdig.Extensions.Footnotes;
/// <summary>
/// A Normalize renderer for a <see cref="FootnoteGroup"/>. It writes every footnote as `[^label]: content`, with the continuation lines indented by four spaces.
/// </summary>
/// <remarks>
/// The parser moves the footnotes to the end of the document, sorts them by their first reference and removes the footnotes without references, so they are written in that order.
/// </remarks>
/// <seealso cref="NormalizeObjectRenderer{FootnoteGroup}" />
public class NormalizeFootnoteGroupRenderer : NormalizeObjectRenderer<FootnoteGroup>
{
/// <summary>
/// Writes the object to the specified renderer.
/// </summary>
protected override void Write(NormalizeRenderer renderer, FootnoteGroup obj)
{
renderer.EnsureLine();
bool first = true;
foreach (var block in obj)
{
if (block is not Footnote footnote)
{
continue;
}
if (!first)
{
renderer.EnsureLine();
renderer.WriteLine();
}
first = false;
WriteFootnote(renderer, footnote);
}
renderer.FinishBlock(true);
}
private static void WriteFootnote(NormalizeRenderer renderer, Footnote footnote)
{
renderer.Write('[').Write(footnote.Label).Write("]:");
// The parser adds a paragraph for the back links if the footnote does not end with one
int lastIndex = -1;
for (int i = footnote.Count - 1; i >= 0; i--)
{
if (!IsBackLinkParagraph(footnote[i]))
{
lastIndex = i;
break;
}
}
if (lastIndex < 0)
{
return;
}
renderer.Write(' ');
renderer.PushIndent(" ");
bool saveIsLastInContainer = renderer.IsLastInContainer;
for (int i = 0; i <= lastIndex; i++)
{
if (!IsBackLinkParagraph(footnote[i]))
{
renderer.IsLastInContainer = i == lastIndex;
renderer.Write(footnote[i]);
}
}
renderer.IsLastInContainer = saveIsLastInContainer;
renderer.PopIndent();
}
private static bool IsBackLinkParagraph(Block block)
{
if (block is not ParagraphBlock paragraph)
{
return false;
}
for (var inline = paragraph.Inline?.FirstChild; inline is not null; inline = inline.NextSibling)
{
if (inline is not FootnoteLink { IsBackLink: true })
{
return false;
}
}
return true;
}
}

View File

@@ -0,0 +1,27 @@
// Copyright (c) Alexandre Mutel. All rights reserved.
// This file is licensed under the BSD-Clause 2 license.
// See the license.txt file in the project root for more information.
using Markdig.Renderers.Normalize;
namespace Markdig.Extensions.Footnotes;
/// <summary>
/// A Normalize renderer for a <see cref="FootnoteLink"/>. It writes a reference such as `[^1]`, and nothing for a back link, which the parser adds.
/// </summary>
/// <seealso cref="NormalizeObjectRenderer{FootnoteLink}" />
public class NormalizeFootnoteLinkRenderer : NormalizeObjectRenderer<FootnoteLink>
{
/// <summary>
/// Writes the object to the specified renderer.
/// </summary>
protected override void Write(NormalizeRenderer renderer, FootnoteLink obj)
{
if (obj.IsBackLink)
{
return;
}
renderer.Write('[').Write(obj.Footnote.Label).Write(']');
}
}

View File

@@ -1,5 +1,5 @@
// Copyright (c) Alexandre Mutel. All rights reserved.
// This file is licensed under the BSD-Clause 2 license.
// This file is licensed under the BSD-Clause 2 license.
// See the license.txt file in the project root for more information.
using Markdig.Syntax;
@@ -7,8 +7,11 @@ using Markdig.Syntax;
namespace Markdig.Renderers.Normalize;
/// <summary>
/// Represents the LinkReferenceDefinitionGroupRenderer type.
/// A Normalize renderer for a <see cref="LinkReferenceDefinitionGroup"/>.
/// </summary>
/// <remarks>
/// A definition that creates its own inline through <see cref="LinkReferenceDefinition.CreateLinkInline"/>, such as the definition of a footnote or of a heading from the auto-identifiers extension, does not come from a `[label]: url` line and is not written.
/// </remarks>
public class LinkReferenceDefinitionGroupRenderer : NormalizeObjectRenderer<LinkReferenceDefinitionGroup>
{
/// <summary>
@@ -16,8 +19,34 @@ public class LinkReferenceDefinitionGroupRenderer : NormalizeObjectRenderer<Link
/// </summary>
protected override void Write(NormalizeRenderer renderer, LinkReferenceDefinitionGroup obj)
{
int lastIndex = -1;
for (int i = obj.Count - 1; i >= 0; i--)
{
if (IsWritten(obj[i]))
{
lastIndex = i;
break;
}
}
if (lastIndex < 0)
{
return;
}
renderer.EnsureLine();
renderer.WriteChildren(obj);
renderer.FinishBlock(false);
bool saveIsLastInContainer = renderer.IsLastInContainer;
for (int i = 0; i <= lastIndex; i++)
{
if (IsWritten(obj[i]))
{
renderer.IsLastInContainer = i == lastIndex;
renderer.Write(obj[i]);
}
}
renderer.IsLastInContainer = saveIsLastInContainer;
renderer.FinishBlock(true);
}
private static bool IsWritten(Block block) => block is not LinkReferenceDefinition { CreateLinkInline: not null };
}

View File

@@ -95,7 +95,7 @@ public abstract class RendererBase : IMarkdownRenderer
/// <summary>
/// Gets or sets the is last in container.
/// </summary>
public bool IsLastInContainer { get; private set; }
public bool IsLastInContainer { get; internal set; }
/// <summary>
/// Gets or sets the maximum nesting depth allowed while rendering Markdown objects.