docs: inject example headings dynamically from pyproject.toml metadata (#6544)

* docs: inject example section headings dynamically from pyproject.toml

Replace static ### headers before <CodeExample> blocks with a Docusaurus
remark plugin (remark-inject-example-headings) that reads titles from
examples-metadata.json at build time. The metadata generator (generate.py)
now includes the title from [tool.flet.metadata] in each example's entry.

Running in beforeDefaultRemarkPlugins so injected headings are picked up
by Docusaurus TOC extraction.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: remove static example headers from subdirectory control docs

The previous pass only covered website/docs/controls/*.md; this extends
it to subdirectories (ads, colorpickers, camera, etc.) by switching to
rglob. Also fixes the script itself to use rglob for future runs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: remove static example headers from types/ and services/ docs

Extends the scan from website/docs/controls/ to all of website/docs/ so
types/, services/, tutorials/, and cookbook/ are covered too.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: inject example descriptions from pyproject.toml, fix duplicate chart headings

Add [tool.flet.metadata].description to 6 chart examples (matplotlib bar chart,
toolbar, plotly line/bar/pie/box). The remark plugin now injects a description
paragraph after the heading when the metadata has one. Static ### headers and
description paragraphs removed from matplotlibchart.md, matplotlibchartwithtoolbar.md,
and plotlychart.md so they no longer duplicate the injected content.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: move chip example descriptions to pyproject.toml, fix duplicate headings

Add multi-paragraph descriptions with inline-code links to assist_chips
and filter_chips pyproject.toml files. Remove static ### headers and
description paragraphs from chip.md.

Upgrades the remark plugin's inline parser to handle [`code`](url) links
and multi-paragraph descriptions (blank-line separated). Keeps hasPrecedingH3
as a safety net for any remaining static ### headers in other docs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: move column scroll example descriptions to pyproject.toml

Add descriptions for infinite_scrolling and programmatic_scroll examples.
Also correct titles from verbose "Column infinite scrolling" / "Column
programmatic scroll" to the shorter "Infinite scrolling" / "Scrolling
programmatically" used as section headings.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(container): rename nested theme example titles to be meaningful

Nested themes 1 -> "Inherited and overridden theme"
Nested themes 2 -> "Page, dark and light themes"
Nested themes 3 -> "Theme mode toggle"

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(cupertinodialogaction): replace 'see there' link with inline examples

Inject the same CodeExample blocks from cupertinoalertdialog.md directly
instead of linking to that page's Examples section.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(datatable): move example descriptions to pyproject.toml

Add titles and descriptions for spacing, adaptive_row_heights, and
sortable_and_selectable examples. Title for spacing updated to
"Horizontal margin and column spacing" and sortable_and_selectable to
"Sortable columns and selectable rows" to match the former static headers.
Static ### headers and descriptions removed from datatable/index.md.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: inject DataTable examples into DataCell, DataRow, DataColumn pages

Replace 'see these' links with inline CodeExample blocks matching
datatable/index.md. The remark plugin will inject headings and
descriptions from pyproject.toml automatically.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(dismissible): add static heading+description in md (hybrid approach); update title in pyproject.toml

dismissible.md uses a static ### header with rich description (admonition,
blockquote, bold text) which is complex to express in plain TOML strings.
The pyproject.toml title is still set for gallery use; hasPrecedingH3 in the
remark plugin skips auto-injection for this example.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor(docs): replace hasPrecedingH3 heuristic with explicit display_title=false in pyproject.toml

Title injection is now on by default for all examples. Set display_title=false
in [tool.flet.metadata] to suppress injection for a specific example (used by
dismissible/remove_on_dismiss_declarative which has a hand-written heading with
rich description in the doc page).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Remove examples and extra heading in docs

Remove the inline Examples sections from DataCell, DataColumn, and DataRow docs (deleted multiple CodeExample/Image blocks), leaving only the ClassAll component. Also remove a redundant "### CodeEditor" heading from the CodeEditor page. This cleans up duplicated example content and relies on centralized/example assets elsewhere.

* docs(drag): inject titles from metadata; restructure DragTarget page

- draggable.md: uncomment CodeExample blocks, remove static ### header
- dragtarget.md: replace 'see these' link with inline CodeExample blocks,
  add examples/example_images frontmatter, switch ClassAll to
  ClassSummary+ClassMembers so description appears above examples

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(expansionpanellist): move Scrolling title+description to pyproject.toml, inject from metadata

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(gesturedetector): move Draggable containers title+description to pyproject.toml, inject from metadata

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(image): move gapless playback title+description to pyproject.toml, inject from metadata

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(navigationbar): inject Adaptive Navigation title+description from metadata

- Extend remark plugin to handle hardcoded CodeExample paths (not just
  frontMatter.examples + '/subfolder/') via HARDCODED_PATH_RE
- Move title+description to adaptive_navigation/pyproject.toml
- Remove static ### header and description from navigationbar/index.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(navigationdrawer): remove static Adaptive navigation header, inject from metadata

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(navigationrail): remove static Adaptive navigation header, inject from metadata

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Update outlinediconbutton.md

* docs(page): inject Mobile device orientation title+description from metadata

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(page): inject Window hidden on start title+description from metadata

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Update RadioGroup docstring and docs

Replace inline backtick reference with a Sphinx cross-reference (:class:`~flet.Radio`) in RadioGroup docstring to improve documentation linking. Remove the redundant "Examples" section from the radiogroup docs page to clean up generated docs; no behavioral changes.

* docs(reorderablelistview): replace 'see this' with inline CodeExample, inject title from metadata

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(router): inject all example titles+descriptions from metadata

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(video): inject all titles+descriptions from metadata; extend plugin for [`code`][ref_id] links

- Remove all static ### headers and descriptions from video/index.md
- Add descriptions (with API cross-references) to all 8 video example pyproject.toml files
- Extend remark plugin parseInline to handle [`code`][ref_id] pattern by emitting
  the text+inlineCode+text triplet that remark-api-links expects for link resolution

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(webview): rename example title to "WebView"

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: remove static ### headers in layoutcontrol and responsiverow, inject from metadata

Convert hardcoded path="..." to path={'...'} so HARDCODED_PATH_RE in the
remark plugin can resolve the metadata key and inject the title.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore: delete obsolete update_example_headers.py script

Static headers have been cleaned up; remark plugin handles injection going forward.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor: rename metadata field description → docs_intro

Renames the [tool.flet.metadata] field from `description` to `docs_intro`
across all 32 pyproject.toml files, updates the generate.py reader and
remark-inject-example-headings plugin accordingly, and regenerates the
examples-metadata.json.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor: move displayTitle opt-out from pyproject.toml to <CodeExample> tag

Instead of reading display_title from [tool.flet.metadata] and storing
displayTitle in examples-metadata.json, the remark plugin now reads a
displayTitle={false} JSX attribute directly from the <CodeExample> element.
Applied to the dismissible remove_on_dismiss_declarative example.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: correct broken scroll_to link in programmatic_scroll docs_intro

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: add .md extension to NavigationRail link in featured_views docs_intro

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: correct NavigationRail link in featured_views docs_intro (folder, not flat file)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: InesaFitsner

sdk/python/examples/apps/router/featured_views/pyproject.toml

@@ -14,7 +14,8 @@ dev = ["flet-cli", "flet-desktop", "flet-web"]
 categories = ["Navigation/Router"]
 
 [tool.flet.metadata]
-title = "Featured views"
+title = "Managed views — full app with NavigationRail"
+docs_intro = "Complete app with [NavigationRail](navigationrail/index.md), stacked project views, and tabbed settings — all using `manage_views=True`."
 controls = ["View", "AppBar", "Column", "Row", "Container", "Button", "Switch", "TextField", "Router", "Route"]
 layout_pattern = "page-navigation"
 complexity = "intermediate"

sdk/python/examples/apps/router/modal_routes/pyproject.toml

@@ -15,6 +15,8 @@ categories = ["Navigation/Router"]
 
 [tool.flet.metadata]
 title = "Modal routes"
+docs_intro = """
+Routes marked `modal=True` are rendered as a fullscreen-dialog overlay on top of the previous (non-modal) location's view stack. A *global* modal is declared at the top level (the URL works from anywhere); a *local* modal is declared as a child of a non-modal parent (the URL embeds the parent's segment, so deep-link works without any state)."""
 controls = ["SafeArea", "Column", "Button", "Text", "TextField", "AppBar", "View", "Router", "Route"]
 layout_pattern = "page-navigation"
 complexity = "intermediate"

sdk/python/examples/apps/router/nested_outlet_views/pyproject.toml

@@ -14,7 +14,8 @@ dev = ["flet-cli", "flet-desktop", "flet-web"]
 categories = ["Navigation/Router"]
 
 [tool.flet.metadata]
-title = "Nested outlet views"
+title = "Managed views — shared layout with outlet"
+docs_intro = "A layout route with `outlet=True` wraps child routes in a shared [View](../controls/view.md). Leaf components return regular controls; the layout provides the View."
 controls = ["View", "AppBar", "Column", "Container", "Button", "Text", "Router", "Route"]
 layout_pattern = "page-navigation"
 complexity = "intermediate"

sdk/python/examples/apps/router/nested_routes/pyproject.toml

@@ -14,7 +14,8 @@ dev = ["flet-cli", "flet-desktop", "flet-web"]
 categories = ["Navigation/Router"]
 
 [tool.flet.metadata]
-title = "Nested routes"
+title = "Managed views — nested routes"
+docs_intro = "Each route component returns a [View](../controls/view.md) with its own [AppBar](../controls/appbar.md). Navigating deeper pushes views onto the stack; swipe-back and AppBar back button pop them."
 controls = ["SafeArea", "Column", "Row", "Button", "Text", "Router", "Route"]
 layout_pattern = "page-navigation"
 complexity = "basic"

sdk/python/examples/apps/router/recursive_routes/pyproject.toml

@@ -15,6 +15,7 @@ categories = ["Navigation/Router"]
 
 [tool.flet.metadata]
 title = "Recursive routes"
+docs_intro = "A route marked `recursive=True` can match itself as its own descendant — one View is emitted per consumed URL segment. Use this for tree-shaped URLs with unbounded depth (e.g. a file browser at `/folder/a/b/c`)."
 controls = ["SafeArea", "Column", "Button", "Text", "TextField", "AppBar", "View", "Router", "Route"]
 layout_pattern = "page-navigation"
 complexity = "intermediate"

sdk/python/examples/controls/core/column/infinite_scrolling/pyproject.toml

@@ -14,7 +14,8 @@ dev = ["flet-cli", "flet-desktop", "flet-web"]
 categories = ["Layout/Column"]
 
 [tool.flet.metadata]
-title = "Column infinite scrolling"
+title = "Infinite scrolling"
+docs_intro = "This example demonstrates adding of list items on-the-fly, as user scroll to the bottom, creating the illusion of infinite list:"
 controls = ["Container", "Column", "Text"]
 layout_pattern = "infinite-list"
 complexity = "basic"

sdk/python/examples/controls/core/column/programmatic_scroll/pyproject.toml

@@ -14,7 +14,8 @@ dev = ["flet-cli", "flet-desktop", "flet-web"]
 categories = ["Layout/Column"]
 
 [tool.flet.metadata]
-title = "Column programmatic scroll"
+title = "Scrolling programmatically"
+docs_intro = "This example shows how to use [`scroll_to()`](scrollablecontrol.md#flet.ScrollableControl.scroll_to) to programmatically scroll a column:"
 controls = ["Container", "Column", "Row", "Button", "Text"]
 layout_pattern = "control-panel"
 complexity = "basic"

sdk/python/examples/controls/core/container/nested_themes_1/pyproject.toml

@@ -14,7 +14,7 @@ dev = ["flet-cli", "flet-desktop", "flet-web"]
 categories = ["Layout/Container"]
 
 [tool.flet.metadata]
-title = "Nested themes 1"
+title = "Inherited and overridden theme"
 controls = ["SafeArea", "Column", "Container", "Button"]
 layout_pattern = "single-panel"
 complexity = "basic"

sdk/python/examples/controls/core/container/nested_themes_2/pyproject.toml

@@ -14,7 +14,7 @@ dev = ["flet-cli", "flet-desktop", "flet-web"]
 categories = ["Layout/Container"]
 
 [tool.flet.metadata]
-title = "Nested themes 2"
+title = "Page, dark and light themes"
 controls = ["SafeArea", "Column", "Row", "Container", "Button", "TextButton", "Text"]
 layout_pattern = "stacked-sections"
 complexity = "basic"

sdk/python/examples/controls/core/container/nested_themes_3/pyproject.toml

@@ -14,7 +14,7 @@ dev = ["flet-cli", "flet-desktop", "flet-web"]
 categories = ["Layout/Container"]
 
 [tool.flet.metadata]
-title = "Nested themes 3"
+title = "Theme mode toggle"
 controls = ["SafeArea", "Column", "Row", "Container", "Button", "Switch"]
 layout_pattern = "stacked-sections"
 complexity = "basic"