Skip to content

docs: generate the Flutter SDK 5.x and experimental 6.x references - #706

Merged
gewenyu99 merged 21 commits into
docs/markdown-reference-adapterfrom
docs/markdown-reference-5
Nov 11, 2026
Merged

gewenyu99 merged 21 commits into
docs/markdown-reference-adapterfrom
docs/markdown-reference-5

Conversation

@gewenyu99

@gewenyu99 gewenyu99 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

💡 Motivation and Context

We have a wave of breaking changes with new major versions for most SDKs. References are now read mostly by bots, not humans, and the HogRef format is heavy. Stacked on #705.

  • Commits references/posthog-flutter-5.md and the latest page, posthog-flutter-reference.md.
  • Commits posthog-flutter-6.md, generated from chore/v6-posthog-ios-4, the 6.0 branch in chore!: Flutter Major Release v6 #637. The getting-started and the platform-view field docs need to land there before that page can be regenerated there.
  • Commits posthog-flutter-migration.md, built from posthog_flutter/MIGRATION.md on chore/v6-posthog-ios-4 (chore!: Flutter Major Release v6 #637).

💚 How did you test it?

  • Every generated page compiles under posthog.com's MDX 1 check.

📝 Checklist

  • All commits are signed
  • I reviewed the submitted code.
  • I added tests to verify the changes.
  • I updated the docs if needed.
  • No breaking change or entry added to the changelog.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Claude Code: Sonnet 5.5 built it and Opus 5.5 opened it, directed by Vincent. Not yet reviewed line by line.

End result

This is what we're building toward: the reference page on posthog.com, rendered from this PR's Markdown in a local posthog.com build with a local Strapi.

Flutter reference on posthog.com

Merge order

🤖 Generated with Claude Code

gewenyu99 and others added 2 commits November 4, 2026 19:55
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Generated from feat/v6-desktop-capture-v1 (#637 and #673) with the capability tags applied.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@gewenyu99 gewenyu99 self-assigned this Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

posthog-flutter Compliance Report

Date: 2026-11-09 18:38:03 UTC
Duration: 96759ms

✅ All Tests Passed!

45/45 tests passed


Capture Tests

✅ 29/29 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 149ms
Format Validation.Event Has Uuid ✅ 118ms
Format Validation.Event Has Lib Properties ✅ 114ms
Format Validation.Distinct Id Is String ✅ 113ms
Format Validation.Token Is Present ✅ 113ms
Format Validation.Custom Properties Preserved ✅ 115ms
Format Validation.Event Has Timestamp ✅ 115ms
Retry Behavior.Retries On 503 ✅ 5326ms
Retry Behavior.Does Not Retry On 400 ✅ 2116ms
Retry Behavior.Does Not Retry On 401 ✅ 2115ms
Retry Behavior.Respects Retry After Header ✅ 8123ms
Retry Behavior.Implements Backoff ✅ 15441ms
Retry Behavior.Retries On 500 ✅ 5223ms
Retry Behavior.Retries On 502 ✅ 5224ms
Retry Behavior.Retries On 504 ✅ 5223ms
Retry Behavior.Max Retries Respected ✅ 15440ms
Deduplication.Generates Unique Uuids ✅ 122ms
Deduplication.Preserves Uuid On Retry ✅ 5221ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 10331ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5223ms
Deduplication.No Duplicate Events In Batch ✅ 121ms
Deduplication.Different Events Have Different Uuids ✅ 114ms
Compression.Sends Gzip When Enabled ✅ 116ms
Batch Format.Uses Proper Batch Structure ✅ 112ms
Batch Format.Flush With No Events Sends Nothing ✅ 107ms
Batch Format.Multiple Events Batched Together ✅ 121ms
Error Handling.Does Not Retry On 403 ✅ 2114ms
Error Handling.Does Not Retry On 413 ✅ 2116ms
Error Handling.Retries On 408 ✅ 5221ms

Feature_Flags Tests

✅ 16/16 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 12ms
Request Payload.Flags Request Uses V2 Query Param ✅ 9ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 9ms
Request Payload.Flags Request Omits Authorization Header ✅ 9ms
Request Payload.Token In Flags Body Matches Init ✅ 9ms
Request Payload.Groups Round Trip ✅ 8ms
Request Payload.Groups Default To Empty Object ✅ 9ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It ✅ 9ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 8ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 8ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 9ms
Request Lifecycle.No Flags Request On Init Alone ✅ 4ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 111ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 15ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 8ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 113ms

@gewenyu99 gewenyu99 changed the title docs: generate the Flutter SDK 5.x reference docs: generate the Flutter SDK 5.x and experimental 6.x references Nov 5, 2026
gewenyu99 and others added 8 commits November 5, 2026 12:55
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The 6.x page comes from chore/v6-posthog-ios-4 (the 6.0 branch) with the
capability tags and getting-started applied. Both still need to land there.

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

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>
…ture flags

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@@ -0,0 +1,3899 @@
---
title: "PostHog Flutter SDK 6.x (experimental)"

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.

[question] This page is generated from chore/v6-posthog-ios-4, and nothing on main regenerates it, so it'll drift as the 6.0 PRs land. It also puts an unreleased API on posthog.com. Should we hold it until 6.0 is close, or regenerate it from the 6.0 branch?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yes, those pages on posthog.com don't go live yet. The pages are going to go up first unindexed, and not in navigation. And we won't merge these PRs either until the SDK is actually released.

gewenyu99 and others added 6 commits November 5, 2026 15:15
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>
Built from posthog_flutter/MIGRATION.md on chore/v6-posthog-ios-4 (#637),
the way the generator builds it once that guide is on main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
gewenyu99 added a commit to PostHog/posthog.com that referenced this pull request Nov 6, 2026
PostHog/posthog-flutter#706 now generates posthog-flutter-migration.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
gewenyu99 and others added 5 commits November 9, 2026 11:40
Rebuilt from posthog_flutter/MIGRATION.md on chore/v6-posthog-ios-4, which now
notes the beforeSend option loss on native and the new flag and event fields.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Member headings show their names again, and the 6.x and migration pages are
rebuilt from the current chore/v6-posthog-ios-4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gewenyu99
gewenyu99 marked this pull request as ready for review November 10, 2026 19:36
@gewenyu99
gewenyu99 requested a review from a team as a code owner November 10, 2026 19:36
@gewenyu99
gewenyu99 requested review from eli-r-ph and turnipdabeets and removed request for a team November 10, 2026 19:36
@veria-ai

veria-ai Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

PR overview

No security issues were found in this pull request.

Reviews

@gewenyu99
gewenyu99 added this pull request to stack #719 November 11, 2026 18:56
@gewenyu99
gewenyu99 merged commit f11de77 into main Nov 11, 2026
31 checks passed
@gewenyu99
gewenyu99 deleted the docs/markdown-reference-5 branch November 11, 2026 18:59
eli-r-ph added a commit to PostHog/posthog.com that referenced this pull request Nov 17, 2026
…r Markdown references (#22061)

* docs(api): add capture v1 API reference

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

* docs(api): list capture v1 request and event limits

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

* docs(api): call the $ settings properties legacy option properties

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

* docs(api): drop product_tour_id from the options table; clarify 429

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

* docs(api): list every capture v1 header and body rule; long event names and non-string ids are new

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

* docs(api): add a field types table to the capture v1 reference

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

* docs(api): say that a parse error names the line and column

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

* docs(api): pin the parse error example to capture's format

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

* docs(api): show the field path in the parse error example

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

* docs(api): show the field-type parse error format

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

* docs(capture-v1): drop the parse error TODO now that the message is live

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

* docs(capture-v1): duplicate uuids keep the first copy; fix the placeholder result

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

* docs(capture-v1): duplicate uuids keep the first copy and raise an ingestion warning

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

* docs(capture-v1): mark 404 and 429 retry behavior as still being decided

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

* docs(capture-v1): reword the retry TODO comments

* docs(capture-v1): tell API users to turn off HTTP library retries

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

* docs(api): fix placeholder result, legacy compression, and quota detail wording on capture v1

* docs(api): list the product_tour_id event option on capture v1

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

* docs(api): say historical_migration applies to the whole capture v1 request

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

* docs(api): resolve capture v1 TODOs with sdk-specs links and settled decisions

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

* docs(api): say which self-hosted versions serve capture v1

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

* docs(capture-v1): retry 404 and 429

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

* docs(api): scope field type errors and legacy option properties on capture v1

* docs(capture-v1): correct api reference errors, limits, and result keys

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

* docs(capture-v1): document the future clamp, results object and ms digits

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

* docs(libraries): add the capture v1 SDK upgrade guide (#21386)

* docs(libraries): add the capture v1 SDK upgrade guide

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

* docs(libraries): note the distinct ID limit and group identify IDs on capture v1

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

* docs(libraries): call the $ settings properties legacy option properties

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

* docs(libraries): drop product_tour_id from the options table

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

* docs(libraries): add a limits section to the capture v1 upgrade guide

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

* docs(libraries): before_send must keep distinct_id a string

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

* docs(capture-v1): note that tracing headers are opt-in for Go and Python

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

* docs(capture-v1): drop the tracing header note; v1 keeps reading them by default

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

* docs(capture-v1): repeated uuids keep the first event

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

* docs(capture-v1): duplicate uuid note now waits only on SDK support

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

* docs(capture-v1): SDKs report dropped duplicate copies; mark 404/429 retries as undecided

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

* docs(capture-v1): reword the retry TODO comment

* docs(capture-v1): Go nested modules move to /v2; link the iOS 4.0 guide

* docs: list feature flag properties with the values the SDK adds

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

* docs: list trace IDs with the SDK values and the GeoIP default per SDK

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

* docs(capture-v1): SDKs follow only same-origin 307 and 308 redirects

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

* docs(sdks): list product_tour_id in the capture v1 option table

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

* docs(sdks): list the historical migration setting for capture v1 SDKs

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

* docs(sdks): resolve capture v1 SDK guide TODOs, add Android and Node details

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

* docs(sdks): proxy checklist for capture v1 headers; link the fixed proxy guides

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

* docs(sdks): proxies must accept 20MB requests for capture v1

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

* docs(capture-v1): sdks retry 404 and 429

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

* docs(libraries): drop the checked AI property names note

* docs(libraries): scope the $set merge and group rules to the SDKs that follow them

* docs(libraries): say which Authorization values a proxy must keep

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

* docs(libraries): keep every PostHog key type in the proxy note

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

* docs(libraries): ask users to check before_send hooks for the v1 event shape

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

* docs(capture-v1): fix sdk upgrade page links, scope, and settings

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

* docs(capture-v1): sdks always write three timestamp digits

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

* docs(capture-v1): node drops a non-string hook distinct id too

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

* docs: link capture v1 from capture, data, AI, and SDK pages (#21387)

* docs: link capture v1 from the capture, data, AI, and SDK pages

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

* docs: note that capture v1 drops long distinct IDs instead of shortening them

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

* docs: separate the SDK page callouts from their TODO comments so MDX parses

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

* docs(data): describe capture v1 duplicate uuid handling as keep-first, drop-rest

* docs(migrate): link capture v1 for historical migrations

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

* docs: capture v1 paths for self-hosted proxies and upgrades; v1 AI needs no $ai_model

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

* docs(self-host): v1 sdks retry 404 before dropping

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

* docs: fix the Flutter capture v1 platforms and drop the checked warning titles note

* docs(capture-v1): add android callout and fix cross-link wording

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

* docs(data): disable_skew_correction still clamps far-future timestamps

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>

* docs(capture-v1): confirm mobile versions and verify upgrade guide snippets

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

* docs(capture-v1): update server sdk pages to the v1 major apis

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

* docs(ai): list the capture v1 sdk versions for large ai events

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

* docs(api): fix capture v1 examples and note unknown token results

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

* docs(data): describe event dedup keys and v1 upsert by resend

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

* docs: fix dedup timestamp rule, rust alias helper, and node and python examples

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

* docs(capture-v1): link the flutter 6 migration guide on github like the other sdks

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

* docs(capture-v1): list python's capture_ai_max_event_bytes in the ai settings table

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

* docs(ai-observability): say which events the capture v1 sdks send through large event capture

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

* docs(libraries): say mobile sdks split a batch on a proxy 413

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

* docs(mcp-analytics): say which sdk versions label mcp events, and filter on $mcp_ events

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

* feat(docs): render Markdown SDK references from Strapi

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

* Make docs redirects cover .md

* docs(python): switch the Python nav to the Markdown reference

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

* feat(docs): serve the current reference at /docs/libraries/<sdk>/reference

Keeps the hand-written library page in place.

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

* docs(python): keep the setup page and point Reference at /reference

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

* feat(docs): write SDK reference Markdown from Strapi as docs pages

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>

* docs(python): list the reference majors under Reference

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

* feat(docs): keep SDK reference majors, migration and the unlinked latest out of search

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

* docs(python): let search index the latest Python reference

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

* fix(docs): keep .md on the old Python reference redirects

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

* docs(libraries): move the mobile capture v1 callouts to the mobile docs PRs

* feat(docs): serve SDK reference majors at N.x.x

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>

* feat(docs): link the Python reference majors at 7.x.x and 8.x.x

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

* feat(docs): link the Go, Rust, iOS, Android and Flutter references

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>

* feat(docs): list the Python reference majors beside Reference

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>

* feat(docs): list each SDK's reference majors beside Reference

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

* Revert "feat(docs): list the Python reference majors beside Reference"

This reverts commit 4a3f767.

* Revert "feat(docs): list each SDK's reference majors beside Reference"

This reverts commit cf8fc34.

* fix(docs): indent nested nav items at any depth

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>

* Revert "fix(docs): indent nested nav items at any depth"

This reverts commit 062a023.

* feat(docs): list the Python reference under a new SDK reference entry

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>

* feat(docs): list the Go, Rust, iOS, Android and Flutter references under 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>

* fix(docs): skip SDK reference rows whose names aren't one path segment

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>

* docs(capture-v1): say mobile sdks keep 404'd events queued and android sends milliseconds

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs(capture-v1): add ios, android, and flutter tabs to the options and ai examples

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* fix(docs): guard the Markdown SDK reference intake

- Time out after 30 seconds and skip the pages on an error, so a Strapi outage doesn't fail or stall the build.
- Skip rows that have no referenceId or version.
- Write only reference, migration and N.x.x pages, so a row can't replace a hand-written page.
- Gitignore the written pages and remove the last build's pages first, so a page that Strapi drops doesn't stay.
- Leave the noindex pages out of the sitemap.

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

* docs(capture-v1): label the mobile code tabs ios, android, and flutter

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* fix(docs): render the Markdown SDK references as plain Markdown, not MDX

The SDK repos generate these pages, and Strapi stores them. The build must
not run code from a row, so the pages are never compiled as MDX:

- gatsby-config.js blocks them from gatsby-plugin-mdx with
  shouldBlockNodeFromTransformation, like the AgentSkill SKILL.md files.
- gatsby/onCreateNode.ts turns each page into an SdkMarkdownReference node.
- src/templates/sdk/SdkMarkdownReference.tsx renders the body with
  react-markdown and rehype-sanitize, like the community posts.

The pages keep the docs layout, the table of contents, and the .md copies
for llms.txt.

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

* docs(capture-v1): events keep their own library name and version

* docs(capture-v1): place the library name in the layer order

* feat(docs): link the JavaScript Web, Node.js and React Native Markdown references

Adds the posthog-js repo's SDKs to the SDK reference nav, so their pages
use the SDK sidebar like Go and Python.

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

* fix(docs): keep the SDK reference's long section list out of the narrow-window header

The Jump to panel lists the sections, so a narrow window doesn't repeat
dozens of them above the page.

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

* fix(docs): index the Markdown SDK references, and build them in previews

- gatsby/algoliaConfig.js indexes the SdkMarkdownReference pages for site
  search, in the shape of the MDX pages. Past and next majors, and the
  migration guides, stay out of search like they stay out of the sitemap.
- gatsby/createPages.ts makes the SDK reference pages before the minimal
  build returns, so Vercel previews have them too.
- The template parses the Markdown again only when the body changes, and
  renders nothing for a code block the sanitizer left empty.
- scripts/posthog-loader.test.cjs stubs ./sdkMarkdownReferences, which its
  sandbox can't resolve from gatsby/.

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

* fix(docs): list the Python reference in the sitemap once the nav links it

#21971 kept /docs/libraries/python/reference out of the sitemap until this
PR links it. This PR removes its noindex header, so the sitemap now lists it
too.

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

* feat(docs): send the JavaScript Web, Node.js and React Native Reference links to the Markdown pages

Like #21973 does for Python: each SDK's Reference link opens its Markdown
reference, the error tracking links open its Capture exception section, and
the HogRef URLs redirect there.

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

* feat(docs): link the Flutter migration guides

PostHog/posthog-flutter#706 now generates posthog-flutter-migration.md.

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

* fix(docs): keep noindex SDK references out of search, and cap their search body

- gatsby/sdkMarkdownReferences.js has one isNoindexSdkReference, which the
  sitemap and site search both use, so the Python reference stays out of
  search until #21973 links it.
- Search reads the first 150,000 characters of a reference. A reference runs
  to about 400 KB, twice the largest page indexed today.
- The createPages comment names the preview deploys, not Vercel.

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

* fix(docs): keep the redirected Python HogRef pages out of the sitemap

- The sitemap skips /docs/references/posthog-python*, which vercel.json
  301s to the Markdown reference, and uses the shared noindex check.
- The Python reference leaves that check, since this PR links it.
- The Python error tracking links open the reference's Capture exception
  section.

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

* fix(docs): keep the redirected JS HogRef pages out of the sitemap

The sitemap skips /docs/references/posthog-js*, posthog-node* and
posthog-react-native*, which vercel.json now 301s, and the error tracking
references page links the JavaScript web and Node.js references' Capture
exception sections.

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

* style: format the redirected SDK reference list

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

* docs(mcp-analytics): per-event python mcp label on 8.0, drop the node 6 first-send note

* docs(mcp-analytics): drop the go v1 capture mode lib note

* docs(api): state the capture v1 PostHog-Sdk-Info limit in bytes

Also say $lib_version is filled when empty or not a string, matching the $lib rule.

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

* docs(capture-v1): note Android keeps hook options and accept v1 in the API eval

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

* docs(capture-v1): use event options in every v1 example and drop legacy property guidance

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

* docs(api): point raw capture v1 callers to options for future majors

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

* docs(capture-v1): document MCP event options, AI per-call options and celery option propagation

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

* docs(capture-v1): match MCP install pages and examples to the v1 majors

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

* docs(capture-v1): use the v2 Go module paths and clarify AI options support

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

* docs(rust): install the 1.0 SDK as the posthog crate

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

* docs(rust): keep TLS on in the error tracking install and accept the posthog crate in the eval

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

* docs(rust): use secret_key and set EvaluateFlagsOptions fields on a default value

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

* docs(go): use the v2 module paths in the remaining Go pages

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

* docs(node): pass captureException options as an object

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

* docs(capture-v1): tidy wording, punctuation, and spacing in the capture v1 pages

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

* docs(rust): pass the project token as a String in the local evaluation snippet

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

* docs(api): keep the future-major hint on the capture v1 legacy option paragraph

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

* docs(mcp): name the event options posthog-node 5 supports

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

* docs(capture-v1): match master's new mcp and ai notes to the v1 majors

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

* docs(capture-v1): fix android guide links and flutter global options

The Android 4.0 migration guide moved to MIGRATION.md at the repo root,
and posthog_flutter 6.0 now has registerOptions.

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

* docs(capture-v1): show how to keep identify calls under a global personless setting

A global or context process_person_profile false reaches identify, alias,
group identify and $set; pass process_person_profile true on the call
(or in before_send on Rust) to keep them.

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

* docs: document captureAi for iOS, Android and Flutter (#21963)

* docs: document captureAi for iOS, Android and Flutter

* docs: put the captureAi note in its own paragraph

Master added a Python capture_ai paragraph right after the large-events
sentence, so appending to that line conflicts. A separate paragraph
before it merges cleanly.

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

* docs(android): link the Android 4.0 upgrade section and list empty event names for captureAi

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

* docs(ios): list empty event names among the captureAi nil cases

* docs(ai): note captureAi is a no-op on Flutter web

Claude-Session: https://claude.ai/code/session_019xLynttdFZAHfqTem5BhPQ

* docs(flutter): list empty event names among the captureAi null cases

* docs(ios): add the compression config row

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* docs(capture-v1): link the mobile AI events sections

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

* docs: pin the Rust installs to 1

The Rust pages move to 1.0 here, so the installs pin 1 instead of
taking the newest release. The transactional emails page and the Rust
tutorial keep the posthog-rs crate, which 1.0 still publishes, and move
from 0.31 to 1.

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

* docs: repin Node and Python installs to posthog-node 6 and posthog 8

Moves every posthog-node@5 install to @6 and every "posthog<8" install
to "posthog>=8,<9", including the ones with an older minimum.

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

* docs: restore the Node minimum versions the repin changed

The repin also matched posthog-node@5 inside two minimum-version notes
and turned them into versions that don't exist. They go back to 5.52.0
and 5.43.0.

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

* docs(capture-v1): resolve release-day markers, Go v2 email install, React Native note

- Remove the release-day TODO markers: every listed major ships on
  release day, so the SDK callouts and the release table stay as written.
- Transactional emails for Go install and import the v2 module.
- The capture v1 SDK guide notes that @posthog/react-native-plugin 3.0
  sends its native events through the iOS and Android 4.0 SDKs.

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

* docs(api): drop the capture v1 pre-merge markers

The page's curl, Python and Node examples return 200 with a per-event
ok result against capture v1.

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

* docs(go): say the deprecated flag methods still work in 1.x and 2.x

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

* docs(sdks): move capture v1 upgrade info onto the SDK pages

- Rename the SDK comparison page to "Choosing a PostHog SDK" and put a
  table of the SDK versions that use capture v1 at the top
- Add a capture v1 callout to the Python, Go, Rust, Node.js, iOS,
  Android, and Flutter pages with links to the migration guide and the
  reference for the older version
- Remove the "Upgrading to capture v1" page and redirect it to
  /docs/libraries
- Share the "New capture API" callout between the legacy capture and
  capture v1 API pages
- Point links to the removed page at the new targets
- Move "SDK bootstrapping" to the end of the SDK nav

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

* chore: drop the formatting-only pricing changes from the master merge

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

* feat(docs): replace the SDK pages with their references in the nav

Each SDK in the nav now lists its reference versions, newest first, and
its migration guide. The separate SDK reference section and the
(experimental) labels are gone. The hand-written SDK pages redirect to
the SDK's reference.

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

* docs: scope the capture v1 pages to the server SDKs in this release

The iOS, Android and Flutter capture v1 majors ship in a later release, with
their own docs.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* docs: fix the capture v1 upgrade intro and the AI capture reference links

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* docs: correct SDK examples and restore capture v1 notes for the new majors

- Rust: use the `posthog` crate on the transactional email page and in the
  analytics tutorial, whose code did not compile.
- Node: object-form `captureException` on two more pages; Fastify guide names
  posthog-node 6.
- Python: positional project token in the error tracking tutorial.
- Go: `SecretKey` in the secret key snippet.
- Restore notes from the retired upgrade page: proxies must return the capture
  response unchanged, older proxy guides, the AI capture spec link, and the
  separate client for historical migration.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* docs: use the posthog crate name in the crates.io source example

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* docs(api): align the capture v1 pages with the capture server and the spec

- Person-only events sent with person processing off are accepted, then
  dropped during ingestion.
- A large AI event sent with plain capture is reported as ai_event_too_big.
- Options are stored as properties only when they change the default.
- Add the ai_byte_rate_limited detail, the decompression error tag, null
  properties, repeated fields, ignored top-level fields and unknown results.
- Self-hosted body limits are a minimum, since the AI endpoint now takes more.
- Scope legacy-only statements on the timestamps, ingestion warnings and
  identify pages, and link the proxy reference from the API page.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* docs(api): say exactly when capture v1 answers 402

The event billing limit refuses the whole request, including exception,
survey and AI events. Name the three product quota details.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* fix(docs): keep the reference SDKs in the SDK comparison table

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>

* docs: point links at the SDK reference pages instead of the retired SDK 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>

* docs: keep the mobile SDK pages until their majors ship

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>

* docs(capture-v1): exception, survey and AI events answer only to their own quota

Matches PostHog/posthog#135788: the events quota drops other events one by
one with events_over_quota, and 402 means no event in the request was left
to store.

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

* docs: keep the web SDK pages, and publish only the server SDK references

The web SDK did not get a major release, so its hand-written pages, nav,
and links stay as they are on master. The build now writes reference
pages only for python, go, rust, and node. Strapi also syncs the web and
mobile SDKs, but those pages are not ready, so the build skips them.

Migration guides are now indexed. The pages for one major version
(N.x.x) stay noindex, because they repeat a reference page.

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

* docs: link the Node.js migration guide on posthog.com, and write SDK versions as 8.x.x and 8.0.0

The capture v1 table on "Choosing a PostHog SDK" linked the Node.js
migration guide on GitHub. It now links /docs/libraries/node/migration,
like the other SDKs, and each SDK name links its reference page.

Version numbers now use the 8.x.x and 8.0.0 form, which the migration
page titles also use.

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

* docs: point links to retired SDK page anchors at the references

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

* docs(workflows): use the posthog crate in the Rust attachment example

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

* docs: point the js config Node tracing link at the Node tracing guide

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

* docs: name posthog-node 6's beforeSend hook in the error tracking guides

posthog-node 6.0 reads only beforeSend (posthog-js #5757), so the Node.js
before_send examples would be silently ignored. The error tracking capture
page and the before-send snippet now show beforeSend for Node.js with a
Node example; the React email page installs posthog-node@6; the capture v1
types note names both hook spellings.

* docs: drop en-dash connectors, add AI and MCP minimums, fix the exception filter key

- Rewrite the en-dash connectors this PR added as sentences, commas or colons.
- Name the minimum versions for event options: @posthog/ai 8.21.0 and
  @posthog/mcp 1.3.0 (their pending minor changesets on capture-v1).
- The web and React Native before-send examples filtered on
  exception["$exception_type"], which no SDK sets on $exception_list entries;
  posthog-js core's ErrorPropertiesBuilder sets `type`, so the filter never
  matched. They now check `type`, as the Node.js example does.

* fix(docs): keep Node.js, Python, Go and Rust in the SDK installation list

This PR replaces those four SDK pages with generated references, which are
not MDX, so the SDK list on the Integrate page lost them. They are listed
explicitly with their references, as LibraryComparison already does.

* fix(docs): fail the build when a published SDK reference is missing

This PR redirects the Node.js, Python, Go and Rust landing pages to their
generated references, so a build that warns past a failed Strapi fetch
would deploy 404s for those SDKs. The fetch now retries twice, and
`gatsby build` fails (reporter.panicOnBuild) when it still fails or when a
published SDK has no reference.md; `gatsby develop` only logs. On Vercel a
failed build keeps the previous deployment live.

---------

Co-authored-by: Eli Reisman <eli.r@posthog.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants