Fix doc and rename ParseSetexHeadings to ParseSetextHeadings (#973)

Adds ParagraphBlockParser.ParseSetextHeadings and keeps ParseSetexHeadings as an [Obsolete] alias, fixes typos in exception messages and XML docs, corrects the footnotes, media links and DisableHtml docs that contradicted the code, and removes the stale PackageReleaseNotes link to changelog.md.
This commit is contained in:
Stefan Greve
2026-10-28 21:02:12 +01:00
committed by GitHub
parent 8946b42492
commit bbf197eaf3
13 changed files with 65 additions and 50 deletions

View File

@@ -25,9 +25,8 @@ reserve breaking changes until the next major version release.
We welcome anyone that wants to contribute to `Markdig` to triage and reply to open issues to help troubleshoot
and fix existing bugs. Here is what you can do:
- Help ensure that existing issues follows the recommendations from the _[Reporting Issues](#reporting-issues)_ section,
- Help ensure that existing issues follow the recommendations from the _[Reporting Issues](#reporting-issues)_ section,
providing feedback to the issue's author on what might be missing.
instructions and code samples.
- Review existing pull requests, and testing patches against real existing applications that use `Markdig`.
- Write a test, or add a missing test case to an existing test.

View File

@@ -54,29 +54,21 @@ This has a long footnote[^long].
- Even lists work in footnotes
- Like this one
## Inline footnotes
You can also define footnotes inline (though this is less common):
```markdown
This has an inline footnote^[This is the inline footnote content].
```
## HTML output
Footnote references become superscript links, and footnote definitions are collected into a `<section>` at the end of the page:
Footnote references become superscript links, and footnote definitions are collected into a `<div>` at the end of the page:
```html
<p>Text with a footnote<a href="#fn:1" class="footnote-ref"><sup>1</sup></a>.</p>
<p>Text with a footnote<a id="fnref:1" href="#fn:1" class="footnote-ref"><sup>1</sup></a>.</p>
<section class="footnotes">
<div class="footnotes">
<hr />
<ol>
<li id="fn:1">
<p>This is the footnote content.
<a href="#fnref:1" class="footnote-back-ref">↩</a></p>
<p>This is the footnote content.<a href="#fnref:1" class="footnote-back-ref">&#8617;</a></p>
</li>
</ol>
</section>
</div>
```
## Rules

View File

@@ -13,10 +13,9 @@ This extension converts image links (`![...](url)`) pointing to known media serv
{.table}
| Service | URL pattern |
|---|---|
| YouTube | `youtube.com/watch?v=...`, `youtu.be/...` |
| YouTube | `www.youtube.com/watch?v=...`, `youtu.be/...` |
| Vimeo | `vimeo.com/...` |
| Dailymotion | `dailymotion.com/video/...` |
| Yandex | `video.yandex.ru/...` |
| Yandex | `music.yandex.ru/album/.../track/...` |
| Odnoklassniki | `ok.ru/video/...` |
## Syntax
@@ -30,7 +29,7 @@ Use standard Markdown image syntax with a media URL:
## HTML output
```html
<iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ"
<iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ" class="youtube"
width="500" height="281"
frameborder="0"
allowfullscreen></iframe>
@@ -38,12 +37,12 @@ Use standard Markdown image syntax with a media URL:
## Direct media files
For direct links to media files the extension supports:
For direct links to media files the extension supports, among others (see `MediaOptions.ExtensionToMimeType`):
{.table}
| Format | Type |
|---|---|
| `.mp4`, `.webm`, `.ogg` | `<video>` element |
| `.mp4`, `.webm`, `.ogv` | `<video>` element |
| `.mp3`, `.wav`, `.ogg` | `<audio>` element |
```markdown

View File

@@ -116,7 +116,7 @@ var pipeline = new MarkdownPipelineBuilder()
| `.UsePreciseSourceLocation()` | Map AST nodes to their exact source location |
| `.EnableTrackTrivia()` | Track whitespace and trivia for roundtripping |
| `.ConfigureNewLine(string)` | Set the newline string for output |
| `.DisableHeadings()` | Disable ATX and Setex heading parsing |
| `.DisableHeadings()` | Disable ATX and setext heading parsing |
| `.DisableHtml()` | Disable HTML block and inline HTML parsing |
> [!CAUTION]

View File

@@ -2,6 +2,7 @@ using System.Text.RegularExpressions;
using Markdig.Extensions.AutoLinks;
using Markdig.Extensions.Tables;
using Markdig.Parsers;
using Markdig.Syntax;
using NUnit.Framework;
@@ -290,6 +291,18 @@ $$
TestParser.TestSpec("[Foo]\n\n[Foo]: bar", "<p><a href=\"bar\">Foo</a></p>", noHeadingsPipeline);
}
[Test]
public void ObsoleteParseSetexHeadingsForwardsToParseSetextHeadings()
{
var parser = new ParagraphBlockParser();
#pragma warning disable CS0618 // Type or member is obsolete
parser.ParseSetexHeadings = false;
Assert.IsFalse(parser.ParseSetextHeadings);
parser.ParseSetextHeadings = true;
Assert.IsTrue(parser.ParseSetexHeadings);
#pragma warning restore CS0618
}
[Test]
public void CanOpenAutoLinksInNewWindow()
{

View File

@@ -23,7 +23,7 @@ public class AlertBlockRenderer : HtmlObjectRenderer<AlertBlock>
}
/// <summary>
/// Gets of sets a delegate to render the kind of the alert.
/// Gets or sets a delegate to render the kind of the alert.
/// </summary>
public Action<HtmlRenderer, StringSlice> RenderKind { get; set; }

View File

@@ -51,7 +51,7 @@ public class AutoIdentifierExtension : IMarkdownExtension
var paragraphBlockParser = pipeline.BlockParsers.FindExact<ParagraphBlockParser>();
if (paragraphBlockParser != null)
{
// Install a hook on the ParagraphBlockParser when a HeadingBlock is actually processed as a Setex heading
// Install a hook on the ParagraphBlockParser when a HeadingBlock is actually processed as a setext heading
paragraphBlockParser.Closed -= HeadingBlockParser_Closed;
paragraphBlockParser.Closed += HeadingBlockParser_Closed;
}
@@ -123,8 +123,8 @@ public class AutoIdentifierExtension : IMarkdownExtension
}
/// <summary>
/// Callback when there is a reference to found to a heading.
/// Note that reference are only working if they are declared after.
/// Callback when a reference to a heading is found.
/// Note that a reference also works if it appears before the heading.
/// </summary>
private static Inline CreateLinkInlineForHeading(InlineProcessor inlineState, LinkReferenceDefinition linkRef, Inline? child)
{

View File

@@ -8,7 +8,6 @@
<TargetFrameworks>net462;netstandard2.0;netstandard2.1;net8.0;net10.0</TargetFrameworks>
<CheckEolTargetFramework>false</CheckEolTargetFramework>
<PackageTags>Markdown CommonMark md html md2html</PackageTags>
<PackageReleaseNotes>https://github.com/xoofx/markdig/blob/master/changelog.md</PackageReleaseNotes>
<PackageLicenseExpression>BSD-2-Clause</PackageLicenseExpression>
<PackageReadmeFile>readme.md</PackageReadmeFile>
<PackageIcon>markdig.png</PackageIcon>

View File

@@ -532,7 +532,7 @@ public static class MarkdownExtensions
}
/// <summary>
/// Adds support for right-to-left content by adding appropriate html attribtues.
/// Adds support for right-to-left content by adding appropriate HTML attributes.
/// </summary>
/// <param name="pipeline">The pipeline</param>
/// <returns>The modified pipeline</returns>
@@ -555,8 +555,11 @@ public static class MarkdownExtensions
}
/// <summary>
/// This will disable the HTML support in the markdown processor (for constraint/safe parsing).
/// This will disable the HTML support in the markdown processor (HTML blocks and inline HTML are rendered as text).
/// </summary>
/// <remarks>
/// Note that this does not sanitize the generated HTML.
/// </remarks>
/// <param name="pipeline">The pipeline.</param>
/// <returns>The modified pipeline</returns>
public static MarkdownPipelineBuilder DisableHtml(this MarkdownPipelineBuilder pipeline)
@@ -578,8 +581,8 @@ public static class MarkdownExtensions
/// <summary>
/// Configures the pipeline using a string that defines the extensions to activate.
/// </summary>
/// <param name="pipeline">The pipeline (e.g: advanced for <see cref="UseAdvancedExtensions"/>, pipetables+gridtables for <see cref="UsePipeTables"/> and <see cref="UseGridTables"/></param>
/// <param name="extensions">The extensions to activate as a string</param>
/// <param name="pipeline">The pipeline</param>
/// <param name="extensions">The extensions to activate as a string (e.g: advanced for <see cref="UseAdvancedExtensions"/>, pipetables+gridtables for <see cref="UsePipeTables"/> and <see cref="UseGridTables"/>)</param>
/// <returns>The modified pipeline</returns>
public static MarkdownPipelineBuilder Configure(this MarkdownPipelineBuilder pipeline, string? extensions)
{
@@ -718,7 +721,7 @@ public static class MarkdownExtensions
}
/// <summary>
/// Disables parsing of ATX and Setex headings
/// Disables parsing of ATX and setext headings
/// </summary>
/// <param name="pipeline">The pipeline.</param>
/// <returns>The modified pipeline</returns>
@@ -727,7 +730,7 @@ public static class MarkdownExtensions
pipeline.BlockParsers.TryRemove<HeadingBlockParser>();
if (pipeline.BlockParsers.TryFind<ParagraphBlockParser>(out var parser))
{
parser.ParseSetexHeadings = false;
parser.ParseSetextHeadings = false;
}
return pipeline;
}
@@ -736,7 +739,7 @@ public static class MarkdownExtensions
/// Enables parsing and tracking of trivia characters
/// </summary>
/// <param name="pipeline">The pipeline.</param>
/// <returns>he modified pipeline</returns>
/// <returns>The modified pipeline</returns>
public static MarkdownPipelineBuilder EnableTrackTrivia(this MarkdownPipelineBuilder pipeline)
{
pipeline.TrackTrivia = true;

View File

@@ -14,9 +14,19 @@ namespace Markdig.Parsers;
public class ParagraphBlockParser : BlockParser
{
/// <summary>
/// Gets or sets the parse setex headings.
/// Gets or sets a value indicating whether setext headings are parsed.
/// </summary>
public bool ParseSetexHeadings { get; set; } = true;
public bool ParseSetextHeadings { get; set; } = true;
/// <summary>
/// Gets or sets a value indicating whether setext headings are parsed.
/// </summary>
[Obsolete("Use ParseSetextHeadings instead.", error: false)]
public bool ParseSetexHeadings
{
get => ParseSetextHeadings;
set => ParseSetextHeadings = value;
}
/// <summary>
/// Attempts to open a block at the current parser position.
@@ -55,9 +65,9 @@ public class ParagraphBlockParser : BlockParser
return BlockState.BreakDiscard;
}
if (!processor.IsCodeIndent && ParseSetexHeadings)
if (!processor.IsCodeIndent && ParseSetextHeadings)
{
return TryParseSetexHeading(processor, block);
return TryParseSetextHeading(processor, block);
}
block.NewLine = processor.Line.NewLine;
block.UpdateSpanEnd(processor.Line.End);
@@ -103,7 +113,7 @@ public class ParagraphBlockParser : BlockParser
return true;
}
private BlockState TryParseSetexHeading(BlockProcessor state, Block block)
private BlockState TryParseSetextHeading(BlockProcessor state, Block block)
{
var line = state.Line;
var sourcePosition = line.Start;

View File

@@ -69,21 +69,21 @@ public class ThematicBreakParser : BlockParser
c = line.NextChar();
}
// If it as less than 3 chars or it is a setex heading and we are already in a paragraph, let the paragraph handle it
// If it has fewer than 3 chars or it is a setext heading and we are already in a paragraph, let the paragraph handle it
var previousParagraph = processor.CurrentBlock as ParagraphBlock;
var isSetexHeading = previousParagraph != null && breakChar == '-' && !hasInnerSpaces;
if (isSetexHeading)
var isSetextHeading = previousParagraph != null && breakChar == '-' && !hasInnerSpaces;
if (isSetextHeading)
{
var parent = previousParagraph!.Parent!;
// A lazy continuation line cannot be a setext underline, so it is a thematic break
if (processor.HasUnmatchedBlocks && (parent is QuoteBlock or ListItemBlock))
{
isSetexHeading = false;
isSetextHeading = false;
}
}
if (breakCharCount < 3 || isSetexHeading)
if (breakCharCount < 3 || isSetextHeading)
{
return BlockState.None;
}

View File

@@ -82,7 +82,7 @@ public abstract class ContainerBlock : Block, IList<Block>, IReadOnlyList<Block>
if (item.Parent != null)
{
ThrowHelper.ArgumentException("Cannot add this block as it as already attached to another container (block.Parent != null)");
ThrowHelper.ArgumentException("Cannot add this block as it is already attached to another container (block.Parent != null)");
}
if (Count == _children.Length)
@@ -232,7 +232,7 @@ public abstract class ContainerBlock : Block, IList<Block>, IReadOnlyList<Block>
if (item.Parent != null)
{
ThrowHelper.ArgumentException("Cannot add this block as it as already attached to another container (block.Parent != null)");
ThrowHelper.ArgumentException("Cannot add this block as it is already attached to another container (block.Parent != null)");
}
if ((uint)index > (uint)Count)
{
@@ -294,7 +294,7 @@ public abstract class ContainerBlock : Block, IList<Block>, IReadOnlyList<Block>
ThrowHelper.ArgumentNullException_item();
if (value.Parent != null)
ThrowHelper.ArgumentException("Cannot add this block as it as already attached to another container (block.Parent != null)");
ThrowHelper.ArgumentException("Cannot add this block as it is already attached to another container (block.Parent != null)");
var existingChild = _children[index].Block;
if (existingChild != null)

View File

@@ -44,10 +44,10 @@ public abstract class LeafBlock : Block
if (value != null)
{
if (value.Parent != null)
ThrowHelper.ArgumentException("Cannot add this inline as it as already attached to another container (inline.Parent != null)");
ThrowHelper.ArgumentException("Cannot add this inline as it is already attached to another container (inline.Parent != null)");
if (value.ParentBlock != null)
ThrowHelper.ArgumentException("Cannot add this inline as it as already attached to another container (inline.ParentBlock != null)");
ThrowHelper.ArgumentException("Cannot add this inline as it is already attached to another container (inline.ParentBlock != null)");
value.ParentBlock = this;
}