Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

docs: structured-output guide does not render its example (dangling "# content is auto-synced" placeholder)

Open
  • Is something wrong?
#723 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@luciobaiocchi is already working on this.

Since Aug 15, 2026.

  • #724 by @luciobaiocchi — open

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Stale
Tech stack
python
Domain
documentation

Research direction

Open sdk/guides/structured-output.mdx and compare the fenced example with examples/01_standalone_sdk/56_structured_output.py. Verify that the guide contains the example code rather than the placeholder and that the rendered Ready-to-run Example section displays the runnable example.

Written by the indexing model from the issue text.

Description

Problem

The Structured Output guide at https://docs.openhands.dev/sdk/guides/structured-output does not show its ready-to-run example. The "Ready-to-run Example" section renders only the literal placeholder line:

# content is auto-synced

…and the code block shows "See all 1 lines" instead of the actual example code.

The example itself exists in the SDK repo: https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/56_structured_output.py — it's just never appearing on the rendered docs page.

Root cause

In sdk/guides/structured-output.mdx, the example block was authored as:

```python icon="python" expandable examples/01_standalone_sdk/56_structured_output.py
# content is auto-synced
```

In this repo the icon="python" expandable examples/... fence is just a label — the example code must be inlined manually between the fences. There is no build-time sync step that injects the file contents; .github/scripts/check_documented_examples.py (in software-agent-sdk) only verifies that a reference string exists in the docs, not that the code is present. The author left # content is auto-synced as a placeholder that was never filled in.

Every other guide inlines its example code this way and renders correctly — e.g. sdk/guides/custom-tools.mdx ("See all 224 lines"), sdk/guides/hello-world.mdx, etc.

Fix

Inline the exact contents of examples/01_standalone_sdk/56_structured_output.py between the fences so the guide renders the ready-to-run example like every other guide. (Done in the linked PR.)

Broader note

This suggests a gap: nothing currently catches a "dangling" example block where the reference exists but the body is a placeholder. A lightweight lint that fails when an expandable examples/... fence contains only a placeholder comment (or fewer than N non-comment lines) would prevent regressions. Worth considering as a follow-up.

This issue was created by an AI agent (OpenHands) on behalf of @luciobaiocchi.

Dominant language
MDX
Stars
16
Forks
63
Avg merge
2d 2h
Merged PRs (30d)
60

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OpenHands/docs

All issues in OpenHands/docs

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.