From 8b4ffd59be3c5d7e80b5c097ec384e7c583ceb0f Mon Sep 17 00:00:00 2001 From: Alexandre Mutel Date: Wed, 4 Nov 2026 21:35:14 +0100 Subject: [PATCH] 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 Co-Authored-By: Claude Opus 5.5 --- site/docs/advanced/renderers.md | 10 ++ src/Markdig.Tests/TestNormalize.cs | 48 ++++++++++ .../CustomContainerExtension.cs | 6 ++ .../NormalizeCustomContainerRenderer.cs | 42 ++++++++ .../Extensions/Footnotes/FootnoteExtension.cs | 7 ++ .../NormalizeFootnoteGroupRenderer.cs | 95 +++++++++++++++++++ .../NormalizeFootnoteLinkRenderer.cs | 27 ++++++ .../LinkReferenceDefinitionGroupRenderer.cs | 37 +++++++- src/Markdig/Renderers/RendererBase.cs | 2 +- 9 files changed, 269 insertions(+), 5 deletions(-) create mode 100644 src/Markdig/Extensions/CustomContainers/NormalizeCustomContainerRenderer.cs create mode 100644 src/Markdig/Extensions/Footnotes/NormalizeFootnoteGroupRenderer.cs create mode 100644 src/Markdig/Extensions/Footnotes/NormalizeFootnoteLinkRenderer.cs diff --git a/site/docs/advanced/renderers.md b/site/docs/advanced/renderers.md index 534ece8c..6566bc95 100644 --- a/site/docs/advanced/renderers.md +++ b/site/docs/advanced/renderers.md @@ -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, diff --git a/src/Markdig.Tests/TestNormalize.cs b/src/Markdig.Tests/TestNormalize.cs index 6ad7a3d0..22fb3433 100644 --- a/src/Markdig.Tests/TestNormalize.cs +++ b/src/Markdig.Tests/TestNormalize.cs @@ -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() { diff --git a/src/Markdig/Extensions/CustomContainers/CustomContainerExtension.cs b/src/Markdig/Extensions/CustomContainers/CustomContainerExtension.cs index 749fcb1f..9b3e3a51 100644 --- a/src/Markdig/Extensions/CustomContainers/CustomContainerExtension.cs +++ b/src/Markdig/Extensions/CustomContainers/CustomContainerExtension.cs @@ -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(); + } + } } diff --git a/src/Markdig/Extensions/CustomContainers/NormalizeCustomContainerRenderer.cs b/src/Markdig/Extensions/CustomContainers/NormalizeCustomContainerRenderer.cs new file mode 100644 index 00000000..d59d54a3 --- /dev/null +++ b/src/Markdig/Extensions/CustomContainers/NormalizeCustomContainerRenderer.cs @@ -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; + +/// +/// A Normalize renderer for a . It writes the content between an opening fence with the info and arguments and a closing fence of the same length. +/// +/// +public class NormalizeCustomContainerRenderer : NormalizeObjectRenderer +{ + /// + /// Writes the object to the specified renderer. + /// + 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); + } +} diff --git a/src/Markdig/Extensions/Footnotes/FootnoteExtension.cs b/src/Markdig/Extensions/Footnotes/FootnoteExtension.cs index 600db2ad..5e430872 100644 --- a/src/Markdig/Extensions/Footnotes/FootnoteExtension.cs +++ b/src/Markdig/Extensions/Footnotes/FootnoteExtension.cs @@ -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(); + normalizeRenderer.ObjectRenderers.AddIfNotAlready(); + } } } diff --git a/src/Markdig/Extensions/Footnotes/NormalizeFootnoteGroupRenderer.cs b/src/Markdig/Extensions/Footnotes/NormalizeFootnoteGroupRenderer.cs new file mode 100644 index 00000000..1e14b3b1 --- /dev/null +++ b/src/Markdig/Extensions/Footnotes/NormalizeFootnoteGroupRenderer.cs @@ -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; + +/// +/// A Normalize renderer for a . It writes every footnote as `[^label]: content`, with the continuation lines indented by four spaces. +/// +/// +/// 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. +/// +/// +public class NormalizeFootnoteGroupRenderer : NormalizeObjectRenderer +{ + /// + /// Writes the object to the specified renderer. + /// + 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; + } +} diff --git a/src/Markdig/Extensions/Footnotes/NormalizeFootnoteLinkRenderer.cs b/src/Markdig/Extensions/Footnotes/NormalizeFootnoteLinkRenderer.cs new file mode 100644 index 00000000..11ec2c22 --- /dev/null +++ b/src/Markdig/Extensions/Footnotes/NormalizeFootnoteLinkRenderer.cs @@ -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; + +/// +/// A Normalize renderer for a . It writes a reference such as `[^1]`, and nothing for a back link, which the parser adds. +/// +/// +public class NormalizeFootnoteLinkRenderer : NormalizeObjectRenderer +{ + /// + /// Writes the object to the specified renderer. + /// + protected override void Write(NormalizeRenderer renderer, FootnoteLink obj) + { + if (obj.IsBackLink) + { + return; + } + + renderer.Write('[').Write(obj.Footnote.Label).Write(']'); + } +} diff --git a/src/Markdig/Renderers/Normalize/LinkReferenceDefinitionGroupRenderer.cs b/src/Markdig/Renderers/Normalize/LinkReferenceDefinitionGroupRenderer.cs index 29ec9040..b78025ce 100644 --- a/src/Markdig/Renderers/Normalize/LinkReferenceDefinitionGroupRenderer.cs +++ b/src/Markdig/Renderers/Normalize/LinkReferenceDefinitionGroupRenderer.cs @@ -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; /// -/// Represents the LinkReferenceDefinitionGroupRenderer type. +/// A Normalize renderer for a . /// +/// +/// A definition that creates its own inline through , 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. +/// public class LinkReferenceDefinitionGroupRenderer : NormalizeObjectRenderer { /// @@ -16,8 +19,34 @@ public class LinkReferenceDefinitionGroupRenderer : NormalizeObjectRenderer 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 }; } diff --git a/src/Markdig/Renderers/RendererBase.cs b/src/Markdig/Renderers/RendererBase.cs index 86e8f468..6fc7922c 100644 --- a/src/Markdig/Renderers/RendererBase.cs +++ b/src/Markdig/Renderers/RendererBase.cs @@ -95,7 +95,7 @@ public abstract class RendererBase : IMarkdownRenderer /// /// Gets or sets the is last in container. /// - public bool IsLastInContainer { get; private set; } + public bool IsLastInContainer { get; internal set; } /// /// Gets or sets the maximum nesting depth allowed while rendering Markdown objects.