docs: smoke-test Visibility wrappers for .md export links#792
Open
leo-notte wants to merge 5 commits into
Open
docs: smoke-test Visibility wrappers for .md export links#792leo-notte wants to merge 5 commits into
leo-notte wants to merge 5 commits into
Conversation
Contributor
WalkthroughThis pull request implements role-based URL routing across the documentation by wrapping internal markdown links and Card components in Estimated code review effort🎯 4 (Complex) | ⏱️ ~75 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.Comment |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
| Filename | Overview |
|---|---|
| docs/src/scripts/wrap_md_links.py | New preprocessor script that wraps internal links and Card hrefs with Visibility pairs. Core logic is sound (reverse-order card transforms, idempotency check, code-region skipping), but EXCLUDE_HREFS only blocks the exact path "/api-reference" rather than the entire "/api-reference/*" subtree, which will produce broken .md links for OpenAPI-rendered endpoints when run on the remaining ~730 MDX files. |
| docs/src/index.mdx | All Cards and inline links wrapped with Visibility human/agent pairs; agent variant carries .md-suffixed hrefs. The core smoke-test change for this PR. |
| docs/src/changelog.mdx | Inline links in changelog entries wrapped with Visibility pairs by the script; output looks correct. |
| docs/src/quickstart.mdx | Card hrefs for Sessions, Agents, and Scraping wrapped with Visibility pairs; transformations are consistent. |
Prompt To Fix All With AI
Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 1
docs/src/scripts/wrap_md_links.py:43-66
**`EXCLUDE_HREFS` only matches the exact root path, not subpaths**
The comment explains that `/api-reference` is OpenAPI-rendered and "only the 3 hand-authored subpages have .md exports" — but `is_excluded` only blocks the path `"/api-reference"` exactly. Any link like `/api-reference/sessions/create` or any other OpenAPI-rendered endpoint would pass the check and receive a `.md` suffix that doesn't exist on the deployed site, producing broken agent navigation when the script is run more broadly.
This is fine for the current smoke-test output (the only api-reference link wrapped here is `/api-reference/authentication`, one of the 3 hand-authored pages), but will silently break agent-facing links for every OpenAPI endpoint reference encountered when the script is applied to the remaining ~730 MDX files.
```python
EXCLUDE_HREFS_EXACT = {"/api-reference"}
EXCLUDE_HREF_PREFIXES = ("/api-reference/",)
def is_excluded(path: str) -> bool:
base = path.split("#", 1)[0].split("?", 1)[0]
return base in EXCLUDE_HREFS_EXACT or base.startswith(EXCLUDE_HREF_PREFIXES)
```
The 3 hand-authored subpages that do have `.md` exports could be opted back in via an explicit `INCLUDE_HREFS` allowlist.
Reviews (2): Last reviewed commit: "docs: include sdk-reference manual pages..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
✅ Eval complete for commit
Ran evals with prompts: ➖ -0.4 pts · Getting Started — B (79.9/100) from B (80.3) · View metricsPrompt text:
Verdict:
Friction points:
Result: B (79.9/100) delta vs baseline: -0.4 pts
Stats: 2m 7s · 15 tool calls · 0 errors · 1 interruption · $0.69 Evaluating agent experience using 2027.dev · View dashboard |
Wraps one Card and one inline link in <Visibility for="humans"|"agents"> on index.mdx with .md-suffixed hrefs in the agent variant. Goal is to verify on a preview deploy that the markdown export at /index.md only contains the .md-suffixed copy and the rendered HTML at / only contains the bare-path copy. If this works, we can build a preprocessor that emits these wrapper pairs across the docs so relative links in the .md export point to other .md pages instead of HTML pages. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds docs/src/scripts/wrap_md_links.py and runs it across hand-authored MDX. Inline markdown links and <Card> hrefs that point to internal pages now get a <Visibility for="humans"> / <Visibility for="agents"> pair — the agent variant uses an .md-suffixed href so the markdown export at /<page>.md emits links that themselves point to other .md exports instead of the HTML pages. Scope: hand-authored MDX only. sdk-reference/ (sphinx_mintlify-generated) and snippets/ (sniptest-generated) are excluded from this run; they'll get the same treatment via their respective generators in a follow-up. The script is idempotent (skips already-wrapped links) and supports --dry-run and --path for spot checks. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Regenerated docs/src/sdk-reference/ against a local sphinx_mintlify
build that emits <Visibility for="humans"> / <Visibility for="agents">
pairs around generated internal links — same pattern as the prior
commit applied to hand-authored MDX. The agent variant uses .md-suffixed
hrefs so the markdown export at /<page>.md links to other .md exports
instead of HTML pages.
Two kinds of changes in this regen:
* 123 Method Cards wrapped (the <CardGroup> on every class index page).
* 80 inline type-annotation links wrapped (e.g. [`AgentStatusResponse`]
in return-type docs).
It also fixes a pre-existing sphinx_mintlify bug where 7 call sites
emitted [Class]{path} (curly braces, not parens) instead of a real
markdown link. That literal-text-with-URL output is now a wrapped
markdown link, which is why the diff is bigger than just the
Visibility wrapping.
The sphinx_mintlify changes themselves live in the sphinx_mintlify
repo and need to be published to PyPI before merging this; instructions
are at sphinx_mintlify's MD_EXPORT_VISIBILITY.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The first preprocessor pass wrapped two patterns it shouldn't have, both
flagged by the broken-link checker:
* Image links — the inline-link regex matched the [alt](src) portion
of , producing !<Visibility>...</Visibility> with .md
appended to image filenames (e.g. /images/bua.png.md). Fix: regex
now requires no preceding ! via negative lookbehind.
* /api-reference Cards — that root path is an OpenAPI-rendered hub
page. Mintlify generates it at runtime and doesn't expose a .md
export, so /api-reference.md returns 404. Fix: an EXCLUDE_HREFS
set the script consults before wrapping; /api-reference is the
only entry for now.
Also reverts the 6 sites that were already incorrectly wrapped: 4
image links (concepts/bua, concepts/personas, concepts/vaults,
integrations/mcp) and 2 /api-reference Cards (features/sessions/puppeteer,
features/functions/invocations).
A dry-run on the full corpus after these changes is a no-op, confirming
the exclusions land only the wrapping that should be there.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
leo-notte
force-pushed
the
experiment/visibility-md-links
branch
from
d72c3d0 to
79985d7
Compare
The earlier preprocessor pass excluded sdk-reference/ wholesale, which
also skipped the 12 hand-authored pages there: 3 root files
(authentication, errors, rate-limits) and 9 under sdk-reference/manual/
(agent, agent_fallback, file_storage, function, index, persona, session,
vault, workflow). Those .md exports were the user-visible regression.
While running on the broader sdk-reference/ tree, two latent bugs
surfaced and are fixed in this commit:
* Inline-link regex matched across <Visibility> wrapper boundaries
in sphinx-gen output like `list[<Visibility>...</Visibility>,
<Visibility>...</Visibility>]` — the outer `[` was unwrapped, the
inner `]` was inside a wrapper, so the regex captured a span that
crossed the boundary. Fix: an overlaps_any_region check rejects
matches whose start is outside but end is inside (or vice versa).
* Cards in sdk-reference/remoteworkflow/* and a handful of "## Returns"
inline links in other sphinx-gen pages were unwrapped because the
prior sphinx_mintlify regen used a stale build cache (and the
Returns-formatter is a code path that still needs wrapping in
sphinx_mintlify). Until the next clean regen, the preprocessor
wraps them — output is functionally identical and a future regen
will replace them.
Net: 17 files changed, 20 inline links + 17 Cards wrapped. Dry-run is
a no-op. The sphinx_mintlify TODO in /home/lboesinger/github/work/
sphinx_mintlify/MD_EXPORT_VISIBILITY.md still applies.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![mendral-app[bot]](https://avatars.githubusercontent.com/in/1975249?s=60&v=4){kind=small}
There was a problem hiding this comment.
Needs attention
The CI failure is expected and intentional — the docs-sdk-generate pre-commit hook re-runs sphinx-build with the current (old) sphinx_mintlify and produces different output than what's committed, because the new sphinx_mintlify with Visibility wrappers hasn't been published to PyPI yet. The commit message explicitly calls this out. One bug to fix before the preprocessor runs at scale: reindent_block in wrap_md_links.py:180 always prepends exactly " " (2 spaces) to lines after the first, ignoring base_indent — Cards nested deeper than 2 spaces will get malformed indentation. Fix: out.append(inner + ln if ln.strip() else ln) for each subsequent line.
Tag @mendral-app with feedback or questions. View session
Comment on lines
+43
to
+66
| # Hrefs whose .md export doesn't exist on the deployed site, so wrapping | ||
| # would produce broken links. /api-reference is OpenAPI-rendered by Mintlify | ||
| # at runtime — only the 3 hand-authored subpages have .md exports. | ||
| EXCLUDE_HREFS = {"/api-reference"} | ||
|
|
||
| VIS_HUMANS_OPEN = '<Visibility for="humans">' | ||
| VIS_AGENTS_OPEN = '<Visibility for="agents">' | ||
| VIS_CLOSE = "</Visibility>" | ||
|
|
||
| # Negative lookbehind on `!` so we don't match the `[alt](src)` portion of | ||
| # an `` image — those should stay as plain markdown images. | ||
| INLINE_LINK_RE = re.compile(r"(?<!!)\[(?P<text>[^\]\n]+)\]\((?P<path>/[^)\s]*)\)") | ||
| CARD_OPEN_RE = re.compile(r'<Card\b[^>]*?\shref="(?P<path>/[^"]+)"[^>]*>') | ||
| VIS_OPEN_RE = re.compile(r'<Visibility\s+for="[^"]+"\s*>') | ||
|
|
||
|
|
||
| def is_external(path: str) -> bool: | ||
| return "://" in path or path.startswith(("mailto:", "tel:", "#")) | ||
|
|
||
|
|
||
| def is_excluded(path: str) -> bool: | ||
| """Path resolves to a page that doesn't have a working .md export.""" | ||
| base = path.split("#", 1)[0].split("?", 1)[0] | ||
| return base in EXCLUDE_HREFS |
There was a problem hiding this comment.
EXCLUDE_HREFS only matches the exact root path, not subpaths
The comment explains that /api-reference is OpenAPI-rendered and "only the 3 hand-authored subpages have .md exports" — but is_excluded only blocks the path "/api-reference" exactly. Any link like /api-reference/sessions/create or any other OpenAPI-rendered endpoint would pass the check and receive a .md suffix that doesn't exist on the deployed site, producing broken agent navigation when the script is run more broadly.
This is fine for the current smoke-test output (the only api-reference link wrapped here is /api-reference/authentication, one of the 3 hand-authored pages), but will silently break agent-facing links for every OpenAPI endpoint reference encountered when the script is applied to the remaining ~730 MDX files.
EXCLUDE_HREFS_EXACT = {"/api-reference"}
EXCLUDE_HREF_PREFIXES = ("/api-reference/",)
def is_excluded(path: str) -> bool:
base = path.split("#", 1)[0].split("?", 1)[0]
return base in EXCLUDE_HREFS_EXACT or base.startswith(EXCLUDE_HREF_PREFIXES)The 3 hand-authored subpages that do have .md exports could be opted back in via an explicit INCLUDE_HREFS allowlist.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/src/scripts/wrap_md_links.py
Line: 43-66
Comment:
**`EXCLUDE_HREFS` only matches the exact root path, not subpaths**
The comment explains that `/api-reference` is OpenAPI-rendered and "only the 3 hand-authored subpages have .md exports" — but `is_excluded` only blocks the path `"/api-reference"` exactly. Any link like `/api-reference/sessions/create` or any other OpenAPI-rendered endpoint would pass the check and receive a `.md` suffix that doesn't exist on the deployed site, producing broken agent navigation when the script is run more broadly.
This is fine for the current smoke-test output (the only api-reference link wrapped here is `/api-reference/authentication`, one of the 3 hand-authored pages), but will silently break agent-facing links for every OpenAPI endpoint reference encountered when the script is applied to the remaining ~730 MDX files.
```python
EXCLUDE_HREFS_EXACT = {"/api-reference"}
EXCLUDE_HREF_PREFIXES = ("/api-reference/",)
def is_excluded(path: str) -> bool:
base = path.split("#", 1)[0].split("?", 1)[0]
return base in EXCLUDE_HREFS_EXACT or base.startswith(EXCLUDE_HREF_PREFIXES)
```
The 3 hand-authored subpages that do have `.md` exports could be opted back in via an explicit `INCLUDE_HREFS` allowlist.
How can I resolve this? If you propose a fix, please make it concise.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/src/features/sessions/puppeteer.mdx (1)
143-180:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winWrap the API Reference card too.
The other Next Steps cards now branch by audience, but this final internal card still points to the bare route for agents. That leaves the export inconsistent with the rest of the block.
Suggested fix
- <Card title="API Reference" icon="code" href="/api-reference"> - Explore the Notte REST API - </Card> + <Visibility for="humans"> + <Card title="API Reference" icon="code" href="/api-reference"> + Explore the Notte REST API + </Card> + </Visibility> + <Visibility for="agents"> + <Card title="API Reference" icon="code" href="/api-reference.md"> + Explore the Notte REST API + </Card> + </Visibility>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/src/features/sessions/puppeteer.mdx` around lines 143 - 180, The API Reference Card inside CardGroup is not wrapped with Visibility like the other entries; duplicate the final Card into two Visibility-wrapped variants (Visibility for="humans" and Visibility for="agents") so each audience gets the correct hrefs (/api-reference for humans and /api-reference.md for agents), using the existing Card component title "API Reference" and icon "code" to match the pattern used for Playwright/Selenium/External Browser Providers.docs/src/sdk-reference/misc/domnode.mdx (1)
20-200:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winThe
DomNodereturn links are updated well overall, butfind()still needs the same treatment.
InteractionDomNode | Noneis still unwrapped, so agents will miss the.mdroute for that type and the page stays inconsistent with the rest of the file.♻️ Suggested fix
-`InteractionDomNode | None` +<Visibility for="humans">[`InteractionDomNode`](/sdk-reference/misc/interactiondomnode)</Visibility><Visibility for="agents">[`InteractionDomNode`](/sdk-reference/misc/interactiondomnode.md)</Visibility> | None🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/src/sdk-reference/misc/domnode.mdx` around lines 20 - 200, The find() return documentation still shows "InteractionDomNode | None" without the Visibility links used elsewhere; update the find() Returns section so the InteractionDomNode part uses the same dual Visibility format as other entries (e.g., <Visibility for="humans">[`InteractionDomNode`](/sdk-reference/misc/interactiondomnode)</Visibility><Visibility for="agents">[`InteractionDomNode`](/sdk-reference/misc/interactiondomnode.md)</Visibility>) and keep the union with None (e.g., ...] | None) so agents get the .md route and the page matches the rest of the file.
🧹 Nitpick comments (1)
docs/src/scripts/wrap_md_links.py (1)
187-200: ⚡ Quick winSkip self-closing
<Card ... />tags before close-tag matching.
transform_cards()assumes paired<Card>...</Card>blocks. Adding a quick guard for self-closing tags avoids accidental cross-block capture if those appear.Suggested hardening
for m in matches: open_start = m.start() if in_any_region(open_start, code_regions) or in_any_region(open_start, vis_regions): continue + if m.group(0).rstrip().endswith("/>"): + continue path = m.group("path") if is_external(path) or is_excluded(path): continue🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/src/scripts/wrap_md_links.py` around lines 187 - 200, transform_cards() currently assumes every CARD_OPEN_RE match is a paired <Card>... so before attempting to find a close tag skip self-closing matches: in the loop over matches (the variable m from CARD_OPEN_RE.finditer(text)) check whether the matched opening tag is self-closing (e.g., the matched text ends with "/>" or via a dedicated "self_close" capture group) and continue if so; this prevents calling find_matching_card_close(new, m.end()) for singleton <Card ... /> tags and avoids cross-block capture.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/src/guides/scraping.mdx`:
- Line 14: Replace the incorrect verb “checkout” in the sentence fragment "For
detailed usage, checkout the <Visibility ...>[Scrape API Reference]..." with the
two-word verb form "check out" so the sentence reads "For detailed usage, check
out the <Visibility ...>[Scrape API Reference]..." (locate the string in
docs/src/guides/scraping.mdx).
---
Outside diff comments:
In `@docs/src/features/sessions/puppeteer.mdx`:
- Around line 143-180: The API Reference Card inside CardGroup is not wrapped
with Visibility like the other entries; duplicate the final Card into two
Visibility-wrapped variants (Visibility for="humans" and Visibility
for="agents") so each audience gets the correct hrefs (/api-reference for humans
and /api-reference.md for agents), using the existing Card component title "API
Reference" and icon "code" to match the pattern used for
Playwright/Selenium/External Browser Providers.
In `@docs/src/sdk-reference/misc/domnode.mdx`:
- Around line 20-200: The find() return documentation still shows
"InteractionDomNode | None" without the Visibility links used elsewhere; update
the find() Returns section so the InteractionDomNode part uses the same dual
Visibility format as other entries (e.g., <Visibility
for="humans">[`InteractionDomNode`](/sdk-reference/misc/interactiondomnode)</Visibility><Visibility
for="agents">[`InteractionDomNode`](/sdk-reference/misc/interactiondomnode.md)</Visibility>)
and keep the union with None (e.g., ...] | None) so agents get the .md route and
the page matches the rest of the file.
---
Nitpick comments:
In `@docs/src/scripts/wrap_md_links.py`:
- Around line 187-200: transform_cards() currently assumes every CARD_OPEN_RE
match is a paired <Card>... so before attempting to find a close tag skip
self-closing matches: in the loop over matches (the variable m from
CARD_OPEN_RE.finditer(text)) check whether the matched opening tag is
self-closing (e.g., the matched text ends with "/>" or via a dedicated
"self_close" capture group) and continue if so; this prevents calling
find_matching_card_close(new, m.end()) for singleton <Card ... /> tags and
avoids cross-block capture.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: e6923e4f-d29c-4b2c-b2e7-c1ba3114d5c0
📒 Files selected for processing (123)
docs/src/changelog.mdxdocs/src/concepts/agents.mdxdocs/src/concepts/file-storage.mdxdocs/src/concepts/functions.mdxdocs/src/concepts/scraping.mdxdocs/src/concepts/sessions.mdxdocs/src/features/agents/configuration.mdxdocs/src/features/agents/fallback.mdxdocs/src/features/agents/lifecycle.mdxdocs/src/features/agents/replay.mdxdocs/src/features/agents/structured-output.mdxdocs/src/features/agents/workflows.mdxdocs/src/features/functions/creating.mdxdocs/src/features/functions/invocations.mdxdocs/src/features/functions/management.mdxdocs/src/features/functions/schedules.mdxdocs/src/features/sessions/browser-controls.mdxdocs/src/features/sessions/browser-profiles.mdxdocs/src/features/sessions/browser-types.mdxdocs/src/features/sessions/captcha-solving.mdxdocs/src/features/sessions/cloudflare-web-bot-auth.mdxdocs/src/features/sessions/configuration.mdxdocs/src/features/sessions/cookies.mdxdocs/src/features/sessions/external-providers.mdxdocs/src/features/sessions/lifecycle.mdxdocs/src/features/sessions/live-view.mdxdocs/src/features/sessions/playwright-vs-notte.mdxdocs/src/features/sessions/playwright.mdxdocs/src/features/sessions/puppeteer.mdxdocs/src/features/sessions/recordings.mdxdocs/src/features/sessions/selenium.mdxdocs/src/features/sessions/stealth-mode.mdxdocs/src/guides/scraping.mdxdocs/src/index.mdxdocs/src/integrations/massive.mdxdocs/src/integrations/stagehand.mdxdocs/src/pricing.mdxdocs/src/product/anything-api.mdxdocs/src/quickstart.mdxdocs/src/rate-limits.mdxdocs/src/scripts/wrap_md_links.pydocs/src/sdk-reference/agentsclient/arun.mdxdocs/src/sdk-reference/agentsclient/arun_custom.mdxdocs/src/sdk-reference/agentsclient/async_watch_logs.mdxdocs/src/sdk-reference/agentsclient/async_watch_logs_and_wait.mdxdocs/src/sdk-reference/agentsclient/create_function.mdxdocs/src/sdk-reference/agentsclient/function_code.mdxdocs/src/sdk-reference/agentsclient/index.mdxdocs/src/sdk-reference/agentsclient/list.mdxdocs/src/sdk-reference/agentsclient/replay.mdxdocs/src/sdk-reference/agentsclient/run.mdxdocs/src/sdk-reference/agentsclient/run_custom.mdxdocs/src/sdk-reference/agentsclient/start.mdxdocs/src/sdk-reference/agentsclient/status.mdxdocs/src/sdk-reference/agentsclient/stop.mdxdocs/src/sdk-reference/agentsclient/wait.mdxdocs/src/sdk-reference/agentsclient/watch_logs.mdxdocs/src/sdk-reference/agentsclient/watch_logs_and_wait.mdxdocs/src/sdk-reference/agentsclient/workflow_code.mdxdocs/src/sdk-reference/agentsclient/workflow_create.mdxdocs/src/sdk-reference/manual/index.mdxdocs/src/sdk-reference/misc/agentsclient.mdxdocs/src/sdk-reference/misc/domnode.mdxdocs/src/sdk-reference/misc/interactiondomnode.mdxdocs/src/sdk-reference/misc/mp4replay.mdxdocs/src/sdk-reference/misc/nottefunction.mdxdocs/src/sdk-reference/misc/nottepersona.mdxdocs/src/sdk-reference/misc/nottevault.mdxdocs/src/sdk-reference/misc/remotefilestorage.mdxdocs/src/sdk-reference/misc/remotesession.mdxdocs/src/sdk-reference/misc/remoteworkflow.mdxdocs/src/sdk-reference/misc/sessionsclient.mdxdocs/src/sdk-reference/notteclient/index.mdxdocs/src/sdk-reference/notteclient/scrape.mdxdocs/src/sdk-reference/nottefunction/fork.mdxdocs/src/sdk-reference/nottefunction/get_run.mdxdocs/src/sdk-reference/nottefunction/index.mdxdocs/src/sdk-reference/nottefunction/replay.mdxdocs/src/sdk-reference/nottefunction/run.mdxdocs/src/sdk-reference/nottefunction/stop_run.mdxdocs/src/sdk-reference/nottepersona/aemails.mdxdocs/src/sdk-reference/nottepersona/asms.mdxdocs/src/sdk-reference/nottepersona/create_number.mdxdocs/src/sdk-reference/nottepersona/delete_number.mdxdocs/src/sdk-reference/nottepersona/emails.mdxdocs/src/sdk-reference/nottepersona/index.mdxdocs/src/sdk-reference/nottepersona/sms.mdxdocs/src/sdk-reference/nottevault/credential_fields_to_dict.mdxdocs/src/sdk-reference/nottevault/get_credit_card.mdxdocs/src/sdk-reference/nottevault/get_credit_card_async.mdxdocs/src/sdk-reference/nottevault/index.mdxdocs/src/sdk-reference/nottevault/replace_credentials.mdxdocs/src/sdk-reference/remoteagent/arun.mdxdocs/src/sdk-reference/remoteagent/async_watch_logs_and_wait.mdxdocs/src/sdk-reference/remoteagent/index.mdxdocs/src/sdk-reference/remoteagent/replay.mdxdocs/src/sdk-reference/remoteagent/run.mdxdocs/src/sdk-reference/remoteagent/start.mdxdocs/src/sdk-reference/remoteagent/status.mdxdocs/src/sdk-reference/remoteagent/stop.mdxdocs/src/sdk-reference/remoteagent/wait.mdxdocs/src/sdk-reference/remoteagent/watch_logs.mdxdocs/src/sdk-reference/remoteagent/watch_logs_and_wait.mdxdocs/src/sdk-reference/remoteagentfallback/index.mdxdocs/src/sdk-reference/remotefilestorage/index.mdxdocs/src/sdk-reference/remotefilestorage/list_downloaded_files.mdxdocs/src/sdk-reference/remotefilestorage/list_uploaded_files.mdxdocs/src/sdk-reference/remotesession/debug_info.mdxdocs/src/sdk-reference/remotesession/execute.mdxdocs/src/sdk-reference/remotesession/get_cookies.mdxdocs/src/sdk-reference/remotesession/index.mdxdocs/src/sdk-reference/remotesession/observe.mdxdocs/src/sdk-reference/remotesession/replay.mdxdocs/src/sdk-reference/remotesession/scrape.mdxdocs/src/sdk-reference/remotesession/set_cookies.mdxdocs/src/sdk-reference/remotesession/status.mdxdocs/src/sdk-reference/remotesession/viewer_notebook.mdxdocs/src/sdk-reference/remoteworkflow/fork.mdxdocs/src/sdk-reference/remoteworkflow/get_run.mdxdocs/src/sdk-reference/remoteworkflow/index.mdxdocs/src/sdk-reference/remoteworkflow/replay.mdxdocs/src/sdk-reference/remoteworkflow/run.mdxdocs/src/sdk-reference/remoteworkflow/stop_run.mdx
|
|
||
| The Scrape API allows you to get the data you want from web pages using a single call. You can scrape page content and capture its data in various formats. | ||
| For detailed usage, checkout the [Scrape API Reference](/sdk-reference/remotesession/scrape). | ||
| For detailed usage, checkout the <Visibility for="humans">[Scrape API Reference](/sdk-reference/remotesession/scrape)</Visibility><Visibility for="agents">[Scrape API Reference](/sdk-reference/remotesession/scrape.md)</Visibility>. |
Contributor
There was a problem hiding this comment.
Fix the wording: “check out” is the verb here.
“Checkout” reads like a noun in this sentence, so switching to “check out” would read more naturally.
♻️ Proposed fix
-For detailed usage, checkout the <Visibility for="humans">[Scrape API Reference](/sdk-reference/remotesession/scrape)</Visibility><Visibility for="agents">[Scrape API Reference](/sdk-reference/remotesession/scrape.md)</Visibility>.
+For detailed usage, check out the <Visibility for="humans">[Scrape API Reference](/sdk-reference/remotesession/scrape)</Visibility><Visibility for="agents">[Scrape API Reference](/sdk-reference/remotesession/scrape.md)</Visibility>.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| For detailed usage, checkout the <Visibility for="humans">[Scrape API Reference](/sdk-reference/remotesession/scrape)</Visibility><Visibility for="agents">[Scrape API Reference](/sdk-reference/remotesession/scrape.md)</Visibility>. | |
| For detailed usage, check out the <Visibility for="humans">[Scrape API Reference](/sdk-reference/remotesession/scrape)</Visibility><Visibility for="agents">[Scrape API Reference](/sdk-reference/remotesession/scrape.md)</Visibility>. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/src/guides/scraping.mdx` at line 14, Replace the incorrect verb
“checkout” in the sentence fragment "For detailed usage, checkout the
<Visibility ...>[Scrape API Reference]..." with the two-word verb form "check
out" so the sentence reads "For detailed usage, check out the <Visibility
...>[Scrape API Reference]..." (locate the string in
docs/src/guides/scraping.mdx).
Comment on lines
+255
to
+258
| if args.path: | ||
| targets = [ROOT / args.path] | ||
| else: | ||
| targets = [p for p in ROOT.rglob("*.mdx") if is_in_scope(p)] |
Contributor
There was a problem hiding this comment.
Constrain --path to docs/src and enforce scope checks.
Line 255–Line 257 bypass is_in_scope() and allow absolute/traversal paths, so this command can rewrite files outside intended directories (and outside .mdx scope).
Suggested fix
def main() -> int:
p = argparse.ArgumentParser()
@@
args = p.parse_args()
if args.path:
- targets = [ROOT / args.path]
+ root_resolved = ROOT.resolve()
+ target = (ROOT / args.path).resolve()
+ try:
+ target.relative_to(root_resolved)
+ except ValueError:
+ p.error("--path must resolve under docs/src")
+ if target.suffix != ".mdx":
+ p.error("--path must point to an .mdx file")
+ if not target.exists():
+ p.error(f"--path does not exist: {args.path}")
+ if not is_in_scope(target):
+ p.error(f"--path is excluded by scope rules: {args.path}")
+ targets = [target]
else:
targets = [p for p in ROOT.rglob("*.mdx") if is_in_scope(p)]
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/src/index.mdxin<Visibility for="humans">/<Visibility for="agents">pairs.agentsvariant uses.md-suffixed hrefs so the markdown export points to other.mdpages instead of bare HTML paths.Why
The
.mdexports from Mintlify (e.g.https://docs.notte.cc/sdk-reference/manual/index.md) preserve internal hrefs as/path— they don't get auto-rewritten to/path.md. That breaks chained markdown navigation for AI tooling. The Mintlify dev server doesn't serve the.mdexport locally, so we need a preview deploy to verify whether<Visibility for="agents">actually filters JSX components like<Card>(the docs only show it filtering paragraph text).Test plan
<preview>/(HTML) — confirm the rendered page is visually unchanged: one Sessions Card, inline "API Reference" link.<preview>/index.md(markdown) — confirm the Sessions entry's href is/concepts/sessions.mdand the inline link is/api-reference/authentication.md. Confirm there is exactly one of each (no duplicates).🤖 Generated with Claude Code
Note
Wraps internal MDX links and
<Card>hrefs in<Visibility for="humans">/<Visibility for="agents">pairs across hand-authored docs and the sphinx-generated SDK reference. The agent variant uses.md-suffixed hrefs so the markdown export at/<page>.mdlinks to other.mdexports rather than bare HTML paths. Addsdocs/src/scripts/wrap_md_links.pyas an idempotent preprocessor with--dry-runsupport.Written by Mendral for commit dd3ce4a.
Summary by CodeRabbit
Documentation
Chores