fix(backend) replace showdown (markdown) library

[grolu]

Summary

This PR replaces the unmaintained showdown Markdown library with a modern, well-maintained Markdown processing pipeline based on unified / remark / rehype.

The goal was to:

• Preserve GitHub-flavored Markdown behavior as closely as possible
• Improve long-term maintainability and security
• Avoid breaking our existing CommonJS-based test setup
• Keep the production API changes minimal and explicit

---

Considerations: Choosing a Markdown Library

I evaluated several Markdown libraries with the requirement that GitHub-style Markdown should be supported either natively or via plugins.

Evaluated candidates

markdown-it

• Core library is well maintained
• Plugin ecosystem is partially unmaintained
• Several important plugins are CommonJS-only
• ESM interop is problematic in modern builds

marked

• Actively maintained and fast

• Limited plugin ecosystem

• Missing features such as emoji support

• Would require manual handling for:

  • External links
  • Task lists
  • GitHub-specific behavior

micromark

• Excellent low-level parser
• Very small and strict API
• Plugin ecosystem is comparatively small
• Requires a lot of custom glue code

unified / remark / rehype (chosen)

• Actively maintained
• Widely adopted in the ecosystem
• Built on top of micromark
• Large plugin ecosystem for GitHub-flavored Markdown
• Clear separation between parsing, transformation, and output
• Downside: larger dependency footprint

Given the trade-offs, unified/remark/rehype was chosen as the best long-term solution.

---

Handling the CommonJS Test Base

All modern Markdown libraries (except markdown-it) are ESM-only.
Our test suite, however, is still CommonJS-based.

To solve this cleanly:

• The actual Markdown implementation was moved to
  markdown.engine.mjs (pure ESM)

• Rollup is configured to copy this file to dist without transpiling

• markdown.js acts as a wrapper:

  • Production code imports the engine directly (ESM)
  • The transpiled markdown.cjs dynamically loads the engine via await import()

• The real markdown.engine.md is used by the markdown test suite only

• All other indirect dependencies to the markdown engine have been replaced by a global mock

This allows:

• Production code to use modern ESM
• Tests to run against the real Markdown engine
• Explicit, isolated async behavior

Additionally:

• A snapshot test suite (markdown.spec.cjs) was introduced
• This was done before the actual code changes to outline parsing differences
• The original Showdown output was captured first
• The new engine was iteratively aligned to match behavior where reasonable

---

Final Markdown Engine (markdown.engine.mjs)

The final implementation uses the following pipeline:

• remark-parse – Markdown parsing
• remark-gfm – GitHub-flavored Markdown
• remark-breaks – GitHub-style line breaks
• remark-emoji – Emoji support
• remark-rehype – Markdown → HTML AST
• rehype-slug – Heading IDs
• rehype-external-links – External links (target="_blank")
• rehype-stringify – HTML output
• sanitize-html – Final security sanitization

Raw HTML is not parsed into the AST, but emitted as raw HTML and sanitized afterward.

---

Changes Compared to Showdown

Dropped features

• Image dimension syntax

  ![alt](image.png =120x80)

  This is a Showdown-specific feature with no direct replacement.
  It is not standard GitHub Markdown and was removed intentionally.

Sanitization improvements

• Explicit allow-list of GitHub-relevant tags:

  • details, summary
  • tables (table, thead, tbody, tr, th, td)
  • headings, code blocks, task lists, etc.

• Explicitly allowed attributes (id, align, class, etc.)

• GitHub task lists supported via disabled checkbox inputs

• transformTags ensures:

  • All links opened in a new tab have noopener noreferrer
  • Only disabled checkbox inputs are allowed

Why still use sanitize-html (and not rehype-sanitize)?

While rehype-sanitize would integrate nicely with the AST and be slightly faster:

• sanitize-html is the de-facto industry standard
• It is widely audited and well understood
• We already need to sanitize non-Markdown HTML elsewhere (e.g. branding)
• Using a single sanitization library everywhere reduces risk and complexity

---

Additional Helper: breakAfterInlineHtmlBlock

This PR also introduces a small helper function:

breakAfterInlineHtmlBlock(input)

Why this is needed

When users paste HTML blocks directly into Markdown (for example <details>, <table>, or headings), Markdown parsers can sometimes “swallow” the following Markdown content if it appears immediately after a closing HTML tag without a blank line.

Example:

<details>
<summary>More</summary>
Some text
</details>
This should be a new paragraph

Without an explicit blank line, many Markdown parsers interpret the following content as part of the HTML block, leading to unexpected rendering.

What the function does

• Scans the Markdown source text (before parsing)
• Detects closing HTML tags that commonly start HTML blocks
• Ensures there is at least one blank line (\n\n) after the closing tag
• Only applies the fix when non-whitespace content follows
• Leaves all other content untouched

Why not solve this in the parser?

This behavior is part of the Markdown specification’s HTML block rules, not a bug in remark or rehype.
Applying this normalization before parsing avoids complex AST manipulation and keeps the pipeline predictable.

---

Async API Changes

The new Markdown engine is asynchronous.

To handle this safely in production code:

• All call sites were updated accordingly

• In the config service, a lazy cache was introduced:

  • Sanitization runs on first request
  • Results are cached (including in-flight promises)
  • No top-level await is required

⚠️ Note: This cache does not currently handle live configuration updates.
This matches existing behavior and can be improved separately if needed.

---

Conclusion

This PR modernizes Markdown handling with a secure, extensible, and well-maintained solution while:

• Preserving GitHub-style behavior
• Keeping test compatibility
• Minimizing production code changes
• Improving long-term maintainability and security

---

Which issue(s) this PR fixes:
Fixes #2707

Special notes for your reviewer:

Release note:

[gardener-robot]

@klocke-io, @holgerkoser You have pull request review open invite, please check

[klocke-io]

/lgtm

[petersutter]

did you encounter a case where adding the fallback || [] was necessary?

[grolu]

Yes I think if the request failed it was undefined but not 100% sure

[petersutter]

then in line 134, do we also need the fallback out of the same reasons or does it behave differently and therefore not needed?
return Promise.all(_.map(githubComments, githubComment =>

[grolu]

hm probably this error did never occur because if issues failed with error it will never try to load comments, but yes if this fails we should also have a fallback. I will add it

[petersutter]

/approve

[gardener-prow]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: klocke-io, petersutter

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [klocke-io,petersutter]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[gardener-prow]

LGTM label has been added.

Details

Git tree hash: 48acc871d2fbc72fbb12ca635401986b980239fa

[gardener-prow]

New changes are detected. LGTM label has been removed.

[grolu]

/cherry-pick hotfix-1.83

[gardener-ci-robot]

@grolu: new pull request created: #2728

Details

In response to this:

/cherry-pick hotfix-1.83

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.