Skip to content

Stop over-escaping text in the Markdown sink - #1070

Merged
slachiewicz merged 2 commits into
apache:masterfrom
slachiewicz:fix-markdown-sink-over-escaping
Aug 8, 2026
Merged

slachiewicz merged 2 commits into
apache:masterfrom
slachiewicz:fix-markdown-sink-over-escaping

Conversation

@slachiewicz

Copy link
Copy Markdown
Member

Three cases where the sink escaped characters that are not special in
Markdown, making generated documents noisy and hard to hand-edit:

  • " and ' were turned into " and '. Markdown is not XML; both
    are ordinary characters there. Only <, > and & still get escaped, so
    text is never mistaken for raw HTML.
  • ( and ) were escaped everywhere. They are only special inside a link
    destination, and destinations are written without going through the
    text escaping, so 'JDK (i.e. Java 6)' no longer becomes 'JDK (i.e.
    Java 6)'.
  • . was escaped after any digit, so a version such as 1.6 came out as
    1.6. It only needs escaping when it would turn leading digits into an
    ordered list marker, i.e. when only whitespace and digits precede it.

Adjusted the one affected expectation in MarkdownSinkTest.

A second change in the same area: a space ends the destination of a Markdown
inline link and starts the optional title, so a destination carrying one does
not resolve. APT allows spaces in both anchors and URLs, so converting a
document like

The {{{#Identity Mapper}Identity Mapper}}

produced [Identity Mapper](#Identity Mapper), which links nowhere. An in-page
anchor now gets the same encoding an anchor definition receives, which is also
what the HTML renderer applies to the anchor it points at, and any other
destination has its spaces percent-encoded.

Part of the wider migration tracked in
apache/maven-doxia-converter#139

Three cases where the sink escaped characters that are not special in
Markdown, making generated documents noisy and hard to hand-edit:

- " and ' were turned into &quot; and &apos;. Markdown is not XML; both
  are ordinary characters there. Only <, > and & still get escaped, so
  text is never mistaken for raw HTML.
- ( and ) were escaped everywhere. They are only special inside a link
  destination, and destinations are written without going through the
  text escaping, so 'JDK (i.e. Java 6)' no longer becomes 'JDK \(i.e.
  Java 6\)'.
- . was escaped after any digit, so a version such as 1.6 came out as
  1\.6. It only needs escaping when it would turn leading digits into an
  ordered list marker, i.e. when only whitespace and digits precede it.

Adjusted the one affected expectation in MarkdownSinkTest.
A space ends the destination of a Markdown inline link and starts the
optional title, so a destination carrying one does not resolve. APT allows
spaces in both anchors and URLs, so converting a document like

  The {{{#Identity Mapper}Identity Mapper}}

produced [Identity Mapper](#Identity Mapper), which links nowhere.

An in-page anchor now gets the same encoding an anchor definition receives,
which is also what the HTML renderer applies to the anchor it points at, and
any other destination has its spaces percent-encoded.
@slachiewicz slachiewicz added enhancement New feature or request and removed maintenance labels Aug 6, 2026
@slachiewicz
slachiewicz merged commit 2c11470 into apache:master Aug 8, 2026
11 checks passed
@github-actions github-actions Bot added this to the 2.1.1 milestone Aug 8, 2026
@slachiewicz
slachiewicz deleted the fix-markdown-sink-over-escaping branch September 7, 2026 10:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant