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

main.py

@@ -77,6 +77,7 @@ def _main_page() -> None:
             .props('accordion no-connectors no-selection-unset icon=chevron_right color=primary')
         tree.visible = False
         spinner = ui.image('/static/loading.gif').classes('w-8 h-8 m-auto').props('no-spinner no-transition')
+        d.override_markdown(spinner, '')
 
         @intersection_observer
         def update_tree() -> None:

tests/test_markdown_response.py

@@ -126,6 +126,17 @@ def build():
     await _assert_markdown(user, build, 'First\n\nSecond')
 
 
+async def test_instance_level_render_markdown_override(user: User):
+    def build():
+        ui.label('Visible')
+        with ui.column() as skipped:
+            ui.label('Hidden by override')
+            ui.image('/static/loading.gif')
+        skipped._render_markdown = lambda: ''  # type: ignore[method-assign]  # pylint: disable=protected-access
+        ui.label('Also visible')
+    await _assert_markdown(user, build, 'Visible\n\nAlso visible')
+
+
 async def test_no_accept_returns_html(user: User):
     @ui.page('/')
     def page():

website/design.py

@@ -1,6 +1,7 @@
 """Design constants and helpers for the NiceGUI website."""
 
 import re
+from typing import TypeVar
 
 from nicegui import ui
 
@@ -89,23 +90,33 @@
 
 # --- Helpers ---
 
+_E = TypeVar('_E', bound=ui.element)
+
+
+def override_markdown(element: _E, markdown: str) -> _E:
+    """Replace ``element``'s `Accept: text/markdown` rendering with the given string."""
+    element._render_markdown = lambda: markdown  # type: ignore[method-assign]  # pylint: disable=protected-access
+    return element
+
+
 def section_heading(subtitle_: str, title_: str) -> None:
     """Render a section heading with a subtitle."""
     ui.label(subtitle_).classes(f'{TEXT_19PX} font-medium {TEXT_SECONDARY}')
-    ui.markdown(title_).classes(f'{TEXT_SECTION_TITLE} font-medium mt-[-12px] [&_em]:not-italic [&_em]:{TEXT_BLUE}')
+    h = ui.markdown(title_).classes(f'{TEXT_SECTION_TITLE} font-medium mt-[-12px] [&_em]:not-italic [&_em]:{TEXT_BLUE}')
+    override_markdown(h, f'# {title_}')
 
 
 def subheading(text: str, *, link: str | None = None, major: bool = False, anchor_name: str | None = None) -> None:
     """Render a subheading with an anchor that can be linked to with a hash."""
     name = anchor_name or create_anchor_name(text)
-    ui.html(f'<div id="{name}"></div>', sanitize=False).style('position: relative; top: -90px')
+    override_markdown(ui.html(f'<div id="{name}"></div>', sanitize=False), '').style('position: relative; top: -90px')
     with ui.row().classes('group gap-2 items-center relative'):
         classes = TEXT_32PX if major else TEXT_24PX
         if link:
-            ui.link(text, link).classes(classes)
+            override_markdown(ui.link(text, link).classes(classes), f'## [{text}]({link})')
         else:
-            ui.label(text).classes(classes)
-        with ui.link(target=f'#{name}').classes('absolute').style('transform: translateX(-150%)'):
+            override_markdown(ui.label(text).classes(classes), f'## {text}')
+        with override_markdown(ui.link(target=f'#{name}').classes('absolute').style('transform: translateX(-150%)'), ''):
             phosphor_icon('ph-link').classes('opacity-0 group-hover:opacity-50 transition-opacity')
 
 
@@ -116,7 +127,7 @@ def create_anchor_name(text: str) -> str:
 
 def phosphor_icon(name: str) -> ui.html:
     """Render a Phosphor duotone icon, e.g. ``phosphor_icon('ph-code')``."""
-    return ui.html(f'<i class="ph-duotone {name}"></i>', sanitize=False).classes('-mb-1')
+    return override_markdown(ui.html(f'<i class="ph-duotone {name}"></i>', sanitize=False).classes('-mb-1'), '')
 
 
 def themed_image(src: str, *, classes: str = '') -> None:

website/documentation/windows.py

@@ -3,7 +3,7 @@
 from nicegui import helpers, ui
 
 from .. import design as d
-from ..design import phosphor_icon
+from ..design import override_markdown, phosphor_icon
 from .intersection_observer import IntersectionObserver as intersection_observer
 
 ICONS = {
@@ -69,7 +69,8 @@ async def handle_intersection():
                 if callable(result):
                     inner_result = result()
                     assert not helpers.should_await(inner_result), 'async functions are not supported in non-lazy demos'
-    return window
+    # Skip in markdown: the lazy preview never hydrates server-side, leaking `localhost:8080` and the loading spinner.
+    return override_markdown(window, '')
 
 
 def _header_row() -> ui.row: