ENG-9266: Support ld+json for docs pages

[carlosabadia]

No description provided.

[linear]

ENG-9266 Make docs support ld+json

[greptile-apps]

Greptile Summary

This PR introduces LD+JSON structured data support for docs pages by reading an ldjson key from flexdown document frontmatter and injecting a <script type="application/ld+json"> tag into the rendered page. The feature is plumbed through both the local flexdown doc path (get_component) and the reflex-package docgen path (get_component_docgen), with appropriate error handling in the latter case.

Key changes:

• pcweb/meta/meta.py: New jsonld_script(data: dict) helper that serialises a dict to a JSON-LD <script> tag, auto-inserting @context: https://schema.org if absent.
• pcweb/pages/docs/__init__.py: Both get_component and get_component_docgen now read ldjson from document metadata at load time; if the value is truthy it is prepended to the rendered content via rx.fragment. The docgen path wraps the metadata load in try/except (OSError, ValueError) to handle missing or unreadable files gracefully.
• One minor robustness gap: the if ldjson: / if _ldjson: guards do not validate that the value is actually a dict, which could produce a confusing TypeError at build time if frontmatter is misconfigured (e.g. ldjson: "string"). Adding isinstance(ldjson, dict) would make this more defensive.

Confidence Score: 5/5

Safe to merge; the only finding is a minor defensive-programming suggestion that does not block production functionality.

All findings are P2 style/robustness suggestions. The core logic is correct: ldjson is captured at load time, the @context auto-injection is sound, and the docgen path has proper error handling for missing files. No data-integrity, security, or runtime breakage risk.

No files require special attention beyond the minor type-guard suggestion in pcweb/pages/docs/__init__.py.

Important Files Changed

Filename	Overview
pcweb/meta/meta.py	Adds jsonld_script utility that wraps any dict into a <script type="application/ld+json"> tag, auto-injecting @context: https://schema.org when absent. Clean, reusable helper.
pcweb/pages/docs/init.py	Wires ldjson frontmatter metadata into both the flexdown and docgen doc compilation paths; ldjson is read at load time and injected via rx.fragment if present. Missing isinstance(ldjson, dict) guard could cause a TypeError at build time on misconfigured frontmatter.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Doc file .md with optional ldjson frontmatter] --> B{Doc type?}
    B -->|flexdown local| C[get_component]
    B -->|reflex-package docgen| D[get_component_docgen]

    C --> C1[load_flexdown_doc]
    C1 --> C2[read ldjson from metadata]
    C2 --> C3{ldjson truthy?}
    C3 -->|Yes| C4[jsonld_script ldjson]
    C3 -->|No| C5[xd.render doc]
    C4 --> C6[rx.fragment - script + rendered]
    C5 --> C7[return toc + rendered]
    C6 --> C7

    D --> D1[try: load_flexdown_doc for metadata]
    D1 -->|OSError or ValueError| D2[ldjson = None]
    D1 -->|success| D3[read ldjson from metadata]
    D3 --> D4{ldjson truthy?}
    D4 -->|Yes| D5[jsonld_script ldjson]
    D4 -->|No| D6[render_docgen_document]
    D5 --> D7[rx.fragment - script + rendered]
    D6 --> D8[return toc + rendered]
    D7 --> D8

    C7 --> E[make_docpage - docpage decorator]
    D8 --> E

    subgraph jsonld_script_fn[jsonld_script]
        J1[data dict input] --> J2{context key present?}
        J2 -->|No| J3[prepend context schema.org]
        J2 -->|Yes| J4[use dict as-is]
        J3 --> J5[rx.el.script with json.dumps]
        J4 --> J5
    end

Loading

_{Reviews (1): Last reviewed commit: "ENG-9266: Support ld+json for docs pages" | Re-trigger Greptile}