Emit heading prefixes, skip decorative HTML and demo previews in markdown stream

[evnchn]

Drafted by @evnchn with Claude Code (Opus 4.7); diff reviewed before pushing. Implements the structural pattern (override_markdown helper) Falko proposed in the #6007 triage.

Motivation

Phase 2 polish for #5889 (markdown content negotiation, merged 2026-04-24). Closes findings 1–3 from discussion #6007:

1. Heading hierarchy missing on docs pages — the H1 came through as literal *Text* Elements, section H2s as plain links. Agents reading the page had no structural cues.
2. Demo panel placeholder leaks — every browser_window rendered localhost:8080 + ![](/static/loading.gif) because the lazy preview never hydrates server-side.
3. Decorative HTML leaks — Phosphor <i class="ph-..."> icons, <div id="..."> anchor targets, and empty [](#anchor) link icons appeared as raw HTML / empty links in the stream.

Per the approved triage, the original three triage PRs each introduced private subclasses + per-call-site monkey-patches. Falko's suggestion was a single shared helper. This PR is that consolidation.

Implementation

Introduces website/design.py:override_markdown(element, markdown):

def override_markdown(element: _E, markdown: str) -> _E:
    element._render_markdown = lambda: markdown  # type: ignore[method-assign]  # pylint: disable=protected-access
    return element

_E = TypeVar('_E', bound=Element) preserves call-site element types so chained .classes() / .style() still type-check. Both suppressions live inside the helper only.

Applied in three places:

• section_heading() — wraps the title ui.markdown with f'# {title_}'.
• subheading() — wraps the anchor ui.html(<div id=...>) and the icon-only ui.link(target=#...) with ''; wraps the actual subheading ui.link / ui.label with f'## [{text}]({link})' or f'## {text}'.
• phosphor_icon() — wraps its ui.html(<i class="ph-...">) with ''.
• browser_window() in website/documentation/windows.py — wraps the whole window with '' (the chrome and lazy preview are irrelevant to a markdown reader).

This collapses what would otherwise be five private subclasses (_MarkdownH1, _MarkdownH2Link, _MarkdownH2Label, _DecorativeHtml, _DecorativeLink) and one inline instance-patch into a single shared helper.

Scope / location decision

Per Falko's suggestion, the helper stays in website/design.py rather than being promoted to nicegui.helpers — it's a site-rendering concern, not a public API contract, until a second user-facing case appears.

Test

Adds test_instance_level_render_markdown_override to tests/test_markdown_response.py, locking in the underlying contract the helper depends on: _render_markdown can be replaced per instance without touching class state.

Composes with #6052

This PR is the companion referenced in #6052's body. #6052 alone surfaces [Button: <i class="ph-duotone ph-copy"></i>] for copy buttons because ui.html._render_markdown() returns the raw content string and the button now recurses into children. With this PR applied, phosphor_icon() returns an element wrapped with override_markdown(..., ''), so the child renders to '', the button's _children_to_markdown().strip() is empty, and the button falls through to ''. Copy-button noise collapses to zero. Either PR can land first; both are needed for the full effect.

Local verification

$ uv run ruff check website/design.py website/documentation/windows.py tests/test_markdown_response.py
All checks passed!

$ uv run pylint website/design.py website/documentation/windows.py
Your code has been rated at 10.00/10

$ uv run pytest tests/test_markdown_response.py -q
33 passed in 0.95s

$ uv run pre-commit run --files website/design.py website/documentation/windows.py tests/test_markdown_response.py
ruff check...............................................................Passed
autopep8.................................................................Passed
trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
fix double quoted strings................................................Passed
codespell................................................................Passed

Same diff is also open at evnchn#150 for fork-side CI verification.

Progress

• The PR title is a short phrase starting with a verb like "Add ...", "Fix ...", "Update ...", "Remove ...", etc.
• The implementation is complete.
• This PR does not address a security issue.
• Pytests have been added (test_instance_level_render_markdown_override).
• Documentation is not necessary (underlying agent-facing rendering change; the public markdown=True opt-in introduced in Add Accept: text/markdown content negotiation for NiceGUI pages #5889 is unchanged).
• No breaking changes to the public API — only behavior of Accept: text/markdown responses on the docs site is affected.

[falkoschindler]

Approving. The override_markdown consolidation is the right shape — one shared helper instead of five private subclasses + a monkey-patch, with both the type: ignore and pylint: disable confined to it.

Verified the markdown stream live (Accept: text/markdown on /documentation/button and /documentation/section_text_elements):

• Heading hierarchy ✓ — H1 (# ui.*button*) from section_heading, H2s from subheading in both branches (## Icons, ## [Label](/documentation/label)).
• Demo previews suppressed ✓ — no localhost:8080 chrome, no demo spinner; the demo code block still survives via python_window.
• Decorative HTML gone ✓ — no raw <i class="ph-…">, anchor <div>s, or empty [](#anchor) icon-links in the content.

A couple of small things I folded in on top while verifying:

• Helper tidy-up — bound the TypeVar to ui.element directly (drops the nicegui.element import) and chained .classes()/.style() inside the override_markdown(...) calls so the with lines read as "build element, then wrap".
• One more placeholder leak — the docs left-drawer lazy-loads its nav tree behind an intersection observer, and its /static/loading.gif placeholder was leaking ![](…) before the content on every docs page. Same family as the browser_window case, so wrapped it with override_markdown(..., '') in main.py. Now 0 occurrences in the stream.

The remaining header/nav and copy-button noise is genuinely separate scope (copy buttons being what #6052 cleans up). 👍