Skip to content

[Waiting on SDK releases] feat(docs): replace the SDK pages with their Markdown references - #22061

Open
gewenyu99 wants to merge 67 commits into
masterfrom
sdk-markdown-reference-js-nav
Open

gewenyu99 wants to merge 67 commits into
masterfrom
sdk-markdown-reference-js-nav

Conversation

@gewenyu99

@gewenyu99 gewenyu99 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Changes

The SDK repos now commit Markdown references for Python, JavaScript Web, Node.js, Go, and Rust. This PR makes those references the SDK docs. iOS, Android, Flutter, and React Native move in #22334, after their majors ship. It is the only nav PR for the Markdown references, and it includes the nav from #21973 and #22003.

  • Nav. Each of the five SDKs in the SDKs list now opens its reference, and lists its reference versions, newest first, and its migration guide. The separate SDK reference section and the "(experimental)" labels are gone.
  • Retired pages. The hand-written SDK pages are deleted: /docs/libraries/<sdk> for the five SDKs, and the six JavaScript Web subpages (usage, config, snippet versioning, security, persistence, and types).
  • Redirects. Each retired page redirects to its SDK's reference. The 25 older redirects that ended on those pages now go straight to the reference. The old /docs/references/posthog-* URLs also redirect to the references.
  • No lost content. The SDK PRs below move everything on the retired pages that the references didn't already say into each SDK's docs/getting-started.md, which each reference shows as its "Getting started" section.
  • src/navs/activeMenu.test.ts checks that every reference version and migration page uses the SDK sidebar.
  • Search can index the latest Python reference. The majors and migration pages stay out of search, and the sitemap leaves out the redirected pages.

The 568 internal links to the retired pages work through the redirects.

Screenshots

The Node.js reference, from a local build with the posthog-js pages in a local Strapi.

State Before After
Light, narrow window
Light, wide window
Dark, narrow window
Dark, wide window

Testing

Check Result
node --test src/navs/activeMenu.test.ts 9 pass
Local pnpm build with the JS pages in a local Strapi Exit 0. The nav opens Node.js under SDK reference.
Console The narrow window shows React errors #418 and #423 before and after this change. No new errors.
Redirects, matched with path-to-regexp 6.3 Each old URL, with or without .md, a version, or a subpath, goes to its SDK's reference. /docs/references/posthog-ios and posthog-jsx don't match.
Prettier No new issues in the changed lines.

Not tested: the Vercel preview, and a build on the current master.

Merge order

🤖 Generated with Claude Code

gewenyu99 and others added 30 commits November 4, 2026 16:23
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rence

Keeps the hand-written library page in place.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Replaces the intake script, version selector and nav code with one small step
in onPreBootstrap. The SDK repo writes each page, front matter included.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…est out of search

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A major's page, such as Python 7, is written to 7.x.x.md, so its URL reads
/docs/libraries/python/7.x.x. The noindex rule matches the new URLs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each SDK's docs nav gets Reference, with its current and experimental majors,
and Migration guides where the SDK has one, like Python's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The sidebar doesn't indent a third nav level, so the majors sit at the SDK's
level as Reference 7.x.x and Reference 8.x.x (experimental).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
TreeMenu built each level's indent as a pl-* class at runtime, and Tailwind only
builds the classes it finds in the source, so a fourth level (pl-18) had no
padding. The same padding is now inline, so every level keeps its indent and
deeper levels get one too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The docs nav gets SDK reference, between SDKs and Frameworks. Python opens its
latest reference and lists 7.x.x, 8.x.x (experimental) and Migration guides,
three levels deep. Python's own SDKs entry keeps Setup and usage and one
Reference link, as on master.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…der SDK reference

Each SDK goes under the SDK reference entry from #21973, three levels deep,
instead of under its own SDKs entry. Their SDKs entries don't change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A referenceId or version with a slash or leading dot could write outside
contents/docs/libraries. The intake now skips such a row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gewenyu99 gewenyu99 changed the title [Waiting on SDK releases] feat(docs): link the Python, JavaScript, Go, Rust, iOS, Android and Flutter Markdown references [Waiting on SDK releases] feat(docs): replace the SDK pages with their Markdown references Nov 12, 2026
turnipdabeets added a commit that referenced this pull request Nov 12, 2026
#22061 deletes libraries/ios/index.mdx and configuration.mdx and serves the
SDK's MIGRATION.md at /docs/libraries/ios/migration, which already covers the
upgrade, event options, captureAi and traits sections. Drop this PR's edits
to those pages and link the install snippet to the migration page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@turnipdabeets

Copy link
Copy Markdown
Contributor

Heads-up from the posthog-android 4.0 release review, about 428cf1b (replacing the SDK pages with their references).

Anchors into the Android page break. The redirect makes /docs/libraries/android resolve, but these lines link sections that no longer exist (#installation, #all-configuration-options, #capturing-events, #push-notifications, #tracing-headers and others), so the link checker may not catch them:

  • integrate/send-events/_snippets/send-events-android.mdx:43
  • logs/installation/android.mdx:21
  • product-analytics/_snippets/how-to-capture-anonymous-events-android.mdx:1
  • product-analytics/_snippets/how-to-capture-identified-events-android.mdx:1
  • product-analytics/autocapture.mdx:360
  • session-replay/_snippets/android-network.mdx:19
  • workflows/configure-channels.mdx:98
  • tutorials/android-ab-tests.md:173, tutorials/android-analytics.md:274,325,357,379, tutorials/android-feature-flags.md:201

The other retired SDK pages likely have the same pattern. #21385, stacked on this PR, also adds #ai-events links into these pages; I left that note there.

The Android migration page was stale, and that's fixed on our side. posthog-android's generator built references/posthog-android-migration.md from docs/migration-*.md, but the 4.0 guide lives in MIGRATION.md, so the page on main is an older draft that still links /docs/libraries/capture-v1. PostHog/posthog-android#976 points the generator at MIGRATION.md and regenerates the page. It goes out with 4.0.

No conflict with #21808. It no longer edits libraries/android/index.mdx.

🤖 Generated with Claude Code

surveys: false
aiObservability: true
errorTracking: true
tracing: true

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page and python/index.mdx were the only ones that set features.tracing. With both deleted, the build fails with Cannot query field "tracing" on type "MdxFrontmatterFeatures", because src/components/LibraryComparison/index.tsx still queries it. That fails "Build & deploy preview" here and on #21385 and #22299, which are stacked on this PR. The deleted pages also remove 11 SDK rows (30 to 19) from the feature comparison table on /docs/libraries, so the table needs a new source for those rows, or at least a schema type for features.

Comment thread src/navs/index.js
name: 'Reference',
url: '/docs/references/posthog-node',
name: 'Migration guide',
url: '/docs/libraries/node/migration',

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the SDK release branches, each references/*-reference.md still holds the previous major, for example pip install "posthog>=7,<8" in posthog-python's. After the SDK majors publish, could you confirm the release regenerated those files and Strapi ingested them, so /docs/libraries/<sdk>/reference and the /migration pages show the new major? posthog-node's release branch has no references/posthog-node-migration.md, so this link depends on the release run generating it.

The comparison table read each SDK's features from its page's
frontmatter. The nine SDK pages this PR retires carried the only
tracing field, so the build failed and those SDKs left the table.
Their features now live in the component and link to the references.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed 7f456f8: no findings. This pull request is large, so the review ran in 4 parts with less depth than usual.

gewenyu99 and others added 2 commits November 13, 2026 11:36
…DK pages

Move the React Native iOS dependency paths into the error tracking
React Native page, since no other page has them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gewenyu99
gewenyu99 requested a review from a team November 13, 2026 17:00
Restore the iOS, Android, Flutter, and React Native pages, nav entries,
redirects, and links to match master. The mobile reference move lands
in its own PR after the mobile majors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Awaiting review

Development

Successfully merging this pull request may close these issues.

4 participants