Update docs for canonical #1519

tkattkat · 2026-01-09T21:42:32Z

why

we need to update the docs to show new languages

what changed

test plan

Summary by cubic

Adds multi-language SDK docs with a sidebar language selector and synced code block languages, covering TypeScript, Python, Java, Go, and Ruby. Adds the canonical OpenAPI spec and auto-syncs SDK pages from GitHub READMEs.

New Features
- Added language selector that syncs with code blocks across pages.
- Updated navigation to language dropdowns for v3.
- Linked docs to the canonical OpenAPI spec.
- Added sync script to generate SDK MDX from GitHub READMEs.
- Added SDK pages for Go, Java, Python, and Ruby.
- Added migration guide for Python v2→v3 and updated the TypeScript migration page.
Migration
- To refresh SDK docs, run: node packages/docs/scripts/sync-sdk-docs.js.

^{Written for commit 833eb27. Summary will update on new commits.}

changeset-bot · 2026-01-09T21:42:37Z

⚠️ No Changeset found

Latest commit: 833eb27

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

cubic-dev-ai

7 issues found across 7 files

Prompt for AI agents (all issues)


Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/docs/scripts/sync-sdk-docs.js">

<violation number="1" location="packages/docs/scripts/sync-sdk-docs.js:55">
P2: The redirect handling has no maximum redirect limit. A redirect loop could cause stack overflow or hang the script indefinitely. Consider adding a redirect counter with a reasonable limit (e.g., 5-10 redirects).</violation>

<violation number="2" location="packages/docs/scripts/sync-sdk-docs.js:114">
P2: This converts Kotlin code blocks to Java, but Kotlin and Java are different languages with different syntax. If the SDK uses Kotlin, the code examples will have incorrect syntax highlighting. If this is intentional for some reason, add a comment explaining why.</violation>
</file>

<file name="packages/docs/v3/sdk/ruby.mdx">

<violation number="1" location="packages/docs/v3/sdk/ruby.mdx:45">
P2: The `x_language` parameter is set to `:typescript` but this is the Ruby SDK documentation. This should likely be `:ruby` to correctly identify the SDK language to the API.</violation>
</file>

<file name="packages/docs/v3/sdk/go.mdx">

<violation number="1" location="packages/docs/v3/sdk/go.mdx:610">
P2: Duration calculation is inverted. `start - end` will produce a negative duration since `start` occurs before `end`. Should be `end - start` for correct elapsed time.</violation>
</file>

<file name="packages/docs/v3/sdk/python.mdx">

<violation number="1" location="packages/docs/v3/sdk/python.mdx:49">
P3: Grammar issue: missing word "you" in the sentence. Should be "If you're using uv, you can follow these steps:"</violation>
</file>

<file name="packages/docs/v3/sdk/java.mdx">

<violation number="1" location="packages/docs/v3/sdk/java.mdx:25">
P3: Code block language identifier should be `groovy` or `kotlin` instead of `java` - this is Gradle build script syntax, not Java code.</violation>

<violation number="2" location="packages/docs/v3/sdk/java.mdx:400">
P2: Invalid Java syntax: the semicolon after `.onCompleteFuture()` terminates the statement, making the subsequent `.whenComplete(...)` call unreachable. This should be a method chain without the semicolon.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

packages/docs/scripts/sync-sdk-docs.js

packages/docs/v3/sdk/ruby.mdx

packages/docs/v3/sdk/go.mdx

packages/docs/v3/sdk/java.mdx

packages/docs/v3/sdk/python.mdx

packages/docs/v3/sdk/java.mdx

greptile-apps

Greptile Overview

Greptile Summary

This PR adds comprehensive multi-language SDK documentation support to the Stagehand docs. The implementation includes:

Core Changes:

Restructured docs.json navigation from simple groups to language-specific dropdowns (TypeScript, Python, Java, Go, Ruby)
Added canonical OpenAPI spec reference linking to Stainless-hosted documentation
Created language-selector.js for syncing language selection across sidebar and code blocks with sessionStorage persistence
Built sync-sdk-docs.js automation script to pull SDK READMEs from GitHub and convert them to MDX

Technical Implementation:
The language selector uses DOM manipulation and MutationObservers to:

Detect and sync sidebar dropdown changes with code block language selectors
Persist user language preference across page navigation via sessionStorage
Conditionally hide the version switcher for non-TypeScript languages
Handle Mintlify's SPA navigation by observing URL changes

The sync script fetches READMEs from four SDK repos (Java, Python, Ruby, Go) and processes them by removing badges, converting relative links to absolute GitHub URLs, cleaning HTML tags, and adding MDX frontmatter with auto-sync notes.

Documentation Structure:
Each language dropdown includes SDK reference pages plus API Reference sections pointing to the canonical OpenAPI spec, alongside shared documentation for First Steps, Basics, Configuration, Best Practices, Integrations, and Migration Guides.

Confidence Score: 5/5

Safe to merge - documentation-only changes with no runtime code impact
This PR consists entirely of documentation updates and tooling scripts. The changes include: (1) restructuring docs.json navigation config to support multi-language dropdowns, (2) adding a client-side JavaScript file for UI enhancements, (3) creating a build-time script to sync SDK docs from GitHub, and (4) adding auto-generated SDK documentation files. None of these changes affect the core Stagehand runtime code. The JSON configuration follows valid Mintlify schema structure, the JavaScript is defensive with proper error handling, and the sync script uses standard Node.js APIs. No tests will break and no existing functionality is impacted.
No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
packages/docs/docs.json	5/5	Added multi-language dropdown navigation structure and OpenAPI spec reference for Python, Java, Go, and Ruby SDKs
packages/docs/language-selector.js	5/5	Custom JavaScript that syncs language selection across sidebar dropdown and code blocks, with session storage persistence
packages/docs/scripts/sync-sdk-docs.js	5/5	Node script to fetch and process SDK READMEs from GitHub repos into MDX documentation files
packages/docs/v3/sdk/python.mdx	5/5	Auto-generated Python SDK documentation from browserbase/stagehand-python README
packages/docs/v3/sdk/go.mdx	5/5	Auto-generated Go SDK documentation from browserbase/stagehand-go README
packages/docs/v3/sdk/java.mdx	5/5	Auto-generated Java SDK documentation from browserbase/stagehand-java README
packages/docs/v3/sdk/ruby.mdx	5/5	Auto-generated Ruby SDK documentation from browserbase/stagehand-ruby README

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Script as sync-sdk-docs.js
    participant GitHub as GitHub API
    participant MDX as SDK MDX Files
    participant Docs as docs.json
    participant Browser as User Browser
    participant LS as language-selector.js

    Note over Dev,LS: Documentation Setup Flow
    
    Dev->>Script: Run node scripts/sync-sdk-docs.js
    Script->>GitHub: Fetch README.md for each SDK
    GitHub-->>Script: Return README content
    Script->>Script: Process README (remove badges, fix links)
    Script->>MDX: Write processed MDX files
    MDX-->>Script: Files created
    
    Note over Dev,LS: User Interaction Flow
    
    Browser->>Docs: Load documentation site
    Docs->>Browser: Render multi-language dropdowns
    Browser->>LS: Initialize language-selector.js
    LS->>LS: Restore language from sessionStorage
    LS->>Browser: Update dropdown & code blocks
    
    Browser->>LS: User selects language (e.g., Python)
    LS->>LS: Store selection in sessionStorage
    LS->>Browser: Update sidebar dropdown text
    LS->>Browser: Sync code block language
    LS->>Browser: Hide/show version switcher

cubic-dev-ai

4 issues found across 34 files (changes from recent commits).

Prompt for AI agents (all issues)


Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/docs/v3/api-reference/java/sdk.mdx">

<violation number="1" location="packages/docs/v3/api-reference/java/sdk.mdx:400">
P2: Syntax error in code example: the semicolon after `.onCompleteFuture();` terminates the method chain prematurely, making `.whenComplete(...)` an invalid standalone statement. Remove the semicolon to fix the method chain.</violation>
</file>

<file name="packages/docs/v3/api-reference/python/sdk.mdx">

<violation number="1" location="packages/docs/v3/api-reference/python/sdk.mdx:49">
P2: Grammatical error: missing word "you" and comma. Should be "If you're using uv, you can follow these steps:"</violation>
</file>

<file name="packages/docs/v3/api-reference/go/sdk.mdx">

<violation number="1" location="packages/docs/v3/api-reference/go/sdk.mdx:282">
P2: Malformed code snippet - URL incorrectly embedded in function call. This looks like a sync error where a relative README link got converted to a full URL. Should be `param.Override[T](value)`.</violation>

<violation number="2" location="packages/docs/v3/api-reference/go/sdk.mdx:292">
P2: Malformed code example - URL incorrectly appears where a numeric argument should be. Should be `param.Override[stagehand.FooParams](12)`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

packages/docs/v3/api-reference/java/sdk.mdx

packages/docs/v3/api-reference/python/sdk.mdx

packages/docs/v3/api-reference/go/sdk.mdx

cubic-dev-ai

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (all issues)


Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/docs/v3/first-steps/quickstart.mdx">

<violation number="1" location="packages/docs/v3/first-steps/quickstart.mdx:15">
P2: Missing punctuation creates a run-on sentence. Add a period or semicolon after "TypeScript" to separate the two independent clauses.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

packages/docs/v3/first-steps/quickstart.mdx

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

pirate

LGTM, go ahead and merge once cubic comments are marked resolved or fixed

tkattkat added 4 commits January 7, 2026 16:04

add openapi docs

679cc91

docs mannnn

bf47b1f

docs man

e1b520e

final touches

f0dfc3c

mintlify bot deployed to staging - packages/docs January 9, 2026 21:43 View deployment

cubic-dev-ai bot reviewed Jan 9, 2026

View reviewed changes

greptile-apps bot reviewed Jan 9, 2026

View reviewed changes

update page

5343e6d

mintlify bot deployed to staging - packages/docs January 12, 2026 20:49 View deployment

update navigation

82db6f5

mintlify bot deployed to staging - packages/docs January 12, 2026 21:34 View deployment

cubic-dev-ai bot reviewed Jan 12, 2026

View reviewed changes

update

4c0caed

mintlify bot deployed to staging - packages/docs January 12, 2026 22:04 View deployment

hide sdk references

dde6913

mintlify bot deployed to staging - packages/docs January 12, 2026 22:17 View deployment

add migration guide & icons for languages

a88a256

mintlify bot deployed to staging - packages/docs January 12, 2026 22:30 View deployment

turn banner into no-op + update python references

ab6d4e8

cubic-dev-ai bot reviewed Jan 13, 2026

View reviewed changes

packages/docs/v3/first-steps/quickstart.mdx Outdated Show resolved Hide resolved

Update packages/docs/v3/first-steps/quickstart.mdx

d3c1d0d

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

mintlify bot deployed to staging - packages/docs January 13, 2026 00:36 View deployment

mintlify bot deployed to staging - packages/docs January 13, 2026 00:41 View deployment

remove unnecessary file

a7950bb

mintlify bot deployed to staging - packages/docs January 13, 2026 00:41 View deployment

remove moe unnecessary files

1762fdc

pirate approved these changes Jan 13, 2026

View reviewed changes

mintlify bot deployed to staging - packages/docs January 13, 2026 00:44 View deployment

add sync script

833eb27

mintlify bot deployed to staging - packages/docs January 13, 2026 00:48 View deployment

pirate approved these changes Jan 13, 2026

View reviewed changes

tkattkat merged commit 6e18760 into main Jan 13, 2026
5 checks passed

Update docs for canonical #1519

Update docs for canonical #1519

Uh oh!

Conversation

tkattkat commented Jan 9, 2026 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

why

what changed

test plan

Summary by cubic

Uh oh!

changeset-bot bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Greptile Overview

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pirate left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tkattkat commented Jan 9, 2026 •

edited by cubic-dev-ai bot

Loading

changeset-bot bot commented Jan 9, 2026 •

edited

Loading