Skip to content

Markdown target: escape a < that would open markup - #273

Merged
dereuromark merged 1 commit into
masterfrom
fix/markdown-escapes-angle-opener
Aug 15, 2026
Merged

Markdown target: escape a < that would open markup#273
dereuromark merged 1 commit into
masterfrom
fix/markdown-escapes-angle-opener

Conversation

@dereuromark

Copy link
Copy Markdown
Contributor

Found while surveying recent sibling-project fixes for things that apply here. Mirrors markup-carve/carve-php#1241.

MarkdownRenderer::escapeText() escapes the Markdown metacharacters (\ ` * _ [ ] #) and leaves < alone. So djot text is emitted as Markdown that a CommonMark reader parses as raw HTML.

On master, this djot:

a<b>c

renders to this Markdown:

a<b>c

and every CommonMark reader takes <b> as an HTML tag. The authored text is gone and markup appears in its place.

The rule

A < is escaped with a backslash when the next character is an ASCII letter, /, ! or ? - the four things that open raw HTML. Every other < is left alone, and > takes nothing: inert mid-line, and at line start it is a block quote marker the line-level handling already covers.

A backslash rather than an entity. The job is to protect the character so it reads back as itself; an entity replaces it with something else.

djot text Markdown before Markdown after
a<b>c a<b>c a\<b>c
a < b and 3 > 2 unchanged unchanged
x<!DOCTYPE y x<!DOCTYPE y x\<!DOCTYPE y

One line, appended after the metacharacter pass so the backslash it inserts is not escaped a second time.

Scope

escapeText() only, which serves Text nodes and a div's title. Code spans, code blocks, autolinks, raw blocks and raw inlines never reach it - a test pins that a code span holding <b> keeps its content verbatim, and that a <https://example.com> autolink still renders as a Markdown link.

MarkdownRenderer::escapeText() escaped the Markdown metacharacters and
left `<` alone, so djot text went out as Markdown that a CommonMark
reader takes as raw HTML: `a<b>c` emitted `a<b>c`, and `<b>` opens a
tag. The authored text is gone and markup appears in its place.

A `<` is now escaped with a backslash when the next character is an
ASCII letter, `/`, `!` or `?` - the four things that open raw HTML - and
left alone otherwise. `>` takes nothing: it is inert mid-line, and at
line start it is a block quote marker the line-level handling already
covers.

A backslash rather than an entity, because the operation is to protect
the character so it reads back as itself; an entity replaces it. So
`a < b and 3 > 2` survives unchanged and `a<b>c` writes `a\<b>c`, which
a CommonMark reader gives back as the text that was written.

The pass runs after the metacharacter pass so the backslash it inserts
is not escaped a second time. Code spans, autolinks and raw nodes never
reach this function and are unaffected.
@codecov

codecov Bot commented Aug 15, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.42%. Comparing base (72442e7) to head (ef78026).

Additional details and impacted files
@@            Coverage Diff            @@
##             master     #273   +/-   ##
=========================================
  Coverage     92.42%   92.42%           
  Complexity     3682     3682           
=========================================
  Files           109      109           
  Lines         10440    10441    +1     
=========================================
+ Hits           9649     9650    +1     
  Misses          791      791           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@dereuromark
dereuromark merged commit fb685e6 into master Aug 15, 2026
6 checks passed
@dereuromark
dereuromark deleted the fix/markdown-escapes-angle-opener branch August 15, 2026 17:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant