Skip to content

Docs: a one-line way to start on the top docs pages (successor to #585) - #616

Open
amitthacker-maker wants to merge 4 commits into
cometchat:mainfrom
amitthacker-maker:docs/entry-point-top-20
Open

amitthacker-maker wants to merge 4 commits into
cometchat:mainfrom
amitthacker-maker:docs/entry-point-top-20

Conversation

@amitthacker-maker

Copy link
Copy Markdown

Successor to #585, which cannot merge from its own branch: validate-branch-name rejects the docs-fix/ prefix and a pull request's head branch cannot be renamed in place. Same work, rebased onto current main, on docs/entry-point-top-20. The review thread on #585 is worth reading alongside this.

What the review asked for, and what changed

Four stack links went to the wrong guide. Two were already fixed on the branch. The other two are fixed here:

Page Was Now
sdk/javascript/3.0/messaging-edit-message.mdx /sdk/javascript/overview, an overview, while the link text promised a guide /sdk/javascript/setup-sdk
notifications/ios-fcm-push-notifications.mdx no stack, so it fell back to the generic chooser stack="iOS"

The guides map had no iOS entry at all, which is why that page could not name its stack. It has one now. Both targets exist on main and are in the navigation.

The root cause is already addressed. href is no longer a prop. The component derives the destination from stack, so the two cannot drift apart the way they did across nine pages. Every remaining stack value resolves in the map; none falls back silently.

Non-blocking items from the same review, where the fix was correctness rather than taste:

  • ui-kit/react/overview.mdx already carries a "Pick your framework" card group for React.js, Next.js, React Router and Astro. Hard-wiring React above it sent a Next.js or Astro reader to the Vite/CRA guide and straight past the picker. The line stays but drops its stack, so it points at the chooser.
  • web-shared/localize, web-shared/reactions-configuration and ui-kit/kotlin/2.0/ui-components are in no docs.json navigation group and have no redirects. They emitted utm_campaign=web-shared, naming a section that does not exist on the site. The entry point is removed from all three.

That takes the set from 18 pages to 15.

Left alone deliberately: rest-api/banned-users/unban renders the line at the bottom, because on an OpenAPI page the body comes after the request and response examples. Dropping the page is a judgement for the reviewer, not a correctness fix.

Still blocking, and not fixable here

The UTM tagging cannot count anything. The parameters sit on internal docs links, chat-call.mdx does not forward query parameters, its only link to the signup host is untagged, and docs.json has no analytics integration. If analytics is added later, self-referral UTMs would overwrite real acquisition sources.

That is a decision, not a defect. Either the entry point ships without the measurement that justified it, or the measurement is redesigned first. Nothing in this pull request resolves it, and the tracking is built in one place in the snippet so it comes out in a single edit either way.

🤖 Generated with Claude Code

AmitAtomChat and others added 4 commits November 17, 2026 21:51
snippets/entry-point.mdx is one line with one link to the Start-here guide for the stack of the page it sits on, tagged utm_source=docs, utm_medium=entry and utm_campaign set to the docs section. One file, so the wording changes in one place. No page uses it yet; the next commit adds it under the H1 of the top 20 docs pages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The top 20 docs pages by Search Console clicks over 90 days, less the ones that correctly get nothing (2: custom landing pages that are themselves a place to start). Each page gets one import and one line directly under its title. Nothing else on any page changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Addresses the review on cometchat#585.

Derive href from stack. href was a pure function of stack but passed as a
separate prop, so the pair was hand-copied on nine pages and had drifted on
four of them. Pages now pass only stack and campaign, and the stack-to-guide
map lives in the component. An unknown stack falls back to the chooser rather
than throwing: a throw would be a build failure, and a build failure in a
table cell is what froze five React pages on live for six weeks.

Three destinations corrected, not four:

- next-tab-based-chat is a Next.js App Router page and linked to the Vite/CRA
  guide. Now Next.js, which is the App Router guide with the client-component
  and SSR steps.
- sdk/android/edit-message is an SDK page and linked to the Android UI Kit.
  Now Android SDK, which is /sdk/android/setup.
- sdk/javascript/.../messaging-edit-message keeps /sdk/javascript/overview.
  Read both candidates: overview is titled "Overview" but its body is the
  full walkthrough (keys, dependency, initialize, register and login, UI
  Kits, widget), while setup-sdk covers only install/import/initialize and
  opens with a v3-to-v4 migration note. The link promises an integration
  guide and overview delivers it. Renamed the key to "JavaScript SDK" so the
  product line is explicit.

The iOS notifications page keeps the chooser. The rule it broke was the rule
itself: platform alone does not determine a destination, because iOS has both
a UI Kit and an SDK and a notifications page is read by users of both.
Sharpened the documented rule instead of the call site.

Keep the AI Integration Quick Reference first on the six pages that have one.
It was the first body element and the entry line displaced it, which put a
marketing sentence above the structured summary that answer engines and
copy-as-Markdown read first. Six pages, not the eight estimated in review.

Also: campaign no longer defaults to "docs", so a page that forgets it is
conspicuous rather than silently plausible; the query is inserted before any
fragment, so an href with a #fragment cannot put the parameters inside it;
and the sentence is one line, so the .md output no longer breaks across three
lines with a lone period.

Tracking is unchanged and built in one place, pending a decision on it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Four blocking link problems from the review, two already fixed on this
branch and two not:

- the JavaScript SDK page promised an integration guide and pointed at
  /sdk/javascript/overview, which is the Overview. Now /sdk/javascript/setup-sdk.
- the iOS FCM notifications page is single stack but named no stack, so
  it fell back to the generic chooser. Now stack="iOS", and the guides
  map gains an iOS entry, which it had been missing entirely.

Both targets exist on main and are in the navigation.

Non-blocking items from the same review, where the fix is a matter of
correctness rather than taste:

- ui-kit/react/overview.mdx already carries a "Pick your framework" card
  group for React.js, Next.js, React Router and Astro. Hard-wiring React
  above it sent a Next.js or Astro reader to the Vite/CRA guide and past
  the picker. The line stays but drops its stack, so it points at the
  chooser.
- web-shared/localize, web-shared/reactions-configuration and
  ui-kit/kotlin/2.0/ui-components are in no docs.json navigation group
  and have no redirects. They emitted utm_campaign=web-shared, naming a
  section that does not exist on the site. The entry point is removed
  from all three.

Left alone deliberately: rest-api/banned-users/unban renders the line at
the bottom because the OpenAPI body comes after the request and response
examples. Dropping the page is a judgement the reviewer should make.

Every remaining stack value resolves in the guides map; none falls back
silently.

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

mintlify Bot commented Nov 17, 2026

Copy link
Copy Markdown

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 4a05ba4.

Approve preview

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

Development

Successfully merging this pull request may close these issues.

2 participants