Skip to content

Docs: a one-line way to start on the top 18 docs pages - #585

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

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

Conversation

@amitthacker-maker

Copy link
Copy Markdown

What this changes

  1. A new snippet, snippets/entry-point.mdx: one line, one link to the Start-here guide for the page's stack. The link carries utm_source=docs, utm_medium=entry and utm_campaign=<docs section>.
  2. That line, directly under the title, on 18 of the 20 docs pages with the most Search Console clicks over the last 90 days. Each page gains two lines (an import and the component) and nothing else changes.

Skipped 2 of the 20: index.mdx and ai-agents.mdx. Both carry mode: "custom" in their
frontmatter, which drops Mintlify's standard layout and the title it renders from title:, so
there is no heading on those two to put a line underneath. That field is the test, and it
separates all 20 pages with no exceptions. Both are also themselves a place to start, so a
start-here link on them would be circular.

(An earlier version of this note said "a custom landing page with no H1". That is misleading:
no page in this set has a # heading, because Mintlify builds the heading from frontmatter.
mode: "custom" is the actual difference.)

Which page each stack links to

The six Start-here guides are the integration guides named in task T-docs-entry.01.

  • React Native: pages under ui-kit/react-native, sdk/react-native, calls/react-native link to /ui-kit/react-native/react-native-cli-integration
  • React: pages under ui-kit/react link to /ui-kit/react/integration-react
  • Flutter: pages under ui-kit/flutter, sdk/flutter, calls/flutter link to /ui-kit/flutter/getting-started
  • iOS: pages under ui-kit/ios, sdk/ios, calls/ios link to /ui-kit/ios/getting-started
  • Android: pages under ui-kit/android, ui-kit/kotlin, sdk/android, calls/android link to /ui-kit/android/getting-started
  • JavaScript: pages under sdk/javascript, calls/javascript link to /sdk/javascript/overview
  • every other page has no single stack and links to /chat-call, where a reader picks one

Why we are asking for this

The problem. Most people who reach our documentation arrive from a search engine, on one
deep page, for one narrow question. They do not arrive at the home page and work inwards. On the
18 pages in this change that is 1,438 clicks and 64,576 impressions over 90 days (Search Console,
measured 2026-10-26). The single biggest is sdk/android/edit-message at 879 clicks.

Those pages answer the question they were found for, and then stop. There is nothing in the text
telling a reader who has never used CometChat where to begin. They can reach the navigation and
the search box, but nothing in what they are actually reading offers them a next step. So a
developer who found us while solving one problem has to go and look for the way in.

What this adds. One sentence, under the title, pointing at the Start-here guide for that
page's stack. That is all. No layout change, no banner, no component to maintain per page.

Why a shared snippet instead of 18 edits. The wording will be wrong at first and will want
changing. If it lives on each page it has to be changed 18 times, then 2,628 times when it rolls
out across the rest of the repo. In one file it changes once. The pages carry an import and a
call, nothing else, so the diff on each page stays two lines forever.

Why these 18 and not all 3,384 pages. We want to read the effect before we commit to the
whole surface. If the line does nothing on the pages with the most traffic, it will do nothing
anywhere, and we would rather find that out on 18 pages than after editing thousands. Nine
further branches covering the rest of the repo are already prepared and deliberately held until
this one has been live long enough to judge.

Why the links carry utm tags. Today we cannot tell whether anyone signs up after reading the
documentation. The tags are there so that becomes countable. Please read the caveat in "Two
things for the reviewer" below: we are not certain this works, and we say so.

What we are asking of you. Review and merge if you are happy. Nothing else is needed from
your side, and nothing about this is urgent enough to interrupt anything. If the wording is
wrong, say so and we will change it in the one file rather than argue about it page by page. If
you would rather this did not go under the title, tell us where instead.

Two things for the reviewer

  1. The preview should show the line under the title on each page, and the link should resolve with the utm tags.
  2. A utm tag on a link inside our own site restarts the analytics session. So counting
    docs-sourced signups is the intent of this change, not something it demonstrates. It stays
    unproven until one test signup is run after this is live, which is task T-docs-entry.07.
  3. One of the 18 pages already fails the strict MDX compiler on main, before this change,
    and still fails after it. It is pre-existing and nothing here caused it. Mintlify itself is
    more lenient than that compiler, so the page builds. The 26 October run recorded the count
    and not which page, and the strict compiler is not configured in the environment this note
    was written in, so it has not been re-run to name it.

How to check it

This branch was cut on 21 October and main has moved 11 commits since, so compare against
the merge-base rather than the tip:

git diff $(git merge-base main docs-fix/entry-point-top-20)..docs-fix/entry-point-top-20

That is 19 files, 99 insertions, 0 deletions. git diff main..docs-fix/entry-point-top-20
reports 139 files and 234 deletions, which is main's own later commits read backwards, not
anything this branch does. A trial merge against current main is clean: the files this branch
touches and the files main gained since the merge-base do not overlap at all.

AmitAtomChat and others added 2 commits October 26, 2026 16:33
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>
@mintlify

mintlify Bot commented Oct 29, 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 bb2fe8e.

Approve preview

@mintlify

mintlify Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
cometchat 🟢 Ready View Preview Oct 29, 2026, 1:38 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

jitvarpatil
jitvarpatil previously approved these changes Oct 30, 2026

@jitvarpatil jitvarpatil 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.

Approving. The change does what it says: one snippet plus two lines on each of 18 pages, no deletions, and a trial merge into current main is clean. All 7 link targets exist and are in the nav, and the line renders correctly under the title on the preview.

Needed before merge

  1. validate-branch-name fails. docs-fix/entry-point-top-20 doesn't match an allowed prefix (docs/, fix/, community/, ...). If that check is required, it blocks the merge on its own. The branch is also 22 commits behind main.

Worth a look (non-blocking)

  1. rest-api/banned-users/unban doesn't get the line under the title. On this OpenAPI page the body renders after the request and response examples, so the line sits at the bottom next to the "Error Guide" sentence. Either accept that or drop the page from the set.

  2. sdk/android/edit-message sends SDK readers to the UI Kit. This is the busiest page in the set (879 of the 1,438 clicks). It links to /ui-kit/android/getting-started, while the JavaScript SDK page links to the SDK overview. /sdk/android/overview exists, so please confirm this is what T-docs-entry.01 intended.

Please check after merge

  1. Click one link on www.cometchat.com. The preview has no /docs base path, so this can't be confirmed before merge. The link shows there as /ui-kit/android/getting-started?utm_…. It should get the prefix on the live site: live pages carry "basePath":"/docs", and the static <a href="/widget/migration"> in the widget snippet comes out as /docs/widget/migration. But I found no other internal link in the docs whose href is computed, so this pattern is unproven. If it misses, every link goes to cometchat.com/ui-kit/..., which returns 404.

Also checked: live pages set a canonical URL, so the ?utm_… variants won't be indexed as duplicates, and the line is in the server-rendered HTML.

@siva-cometchat siva-cometchat 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.

Thanks for this. The idea is good, the component renders correctly (checked the OpenAPI page too, where the body lands right after the generated description), and keeping the wording in one snippet is the right call.

Two things block it for me, both with inline comments:

  1. The UTM tagging cannot meet its stated goal. The parameters sit on internal links, the destination's signup link is untagged, and docs.json has no analytics integration, so T-docs-entry.07 will count nothing. If analytics is added later, self-referral UTMs will overwrite real acquisition sources. Details on snippets/entry-point.mdx:22.
  2. Four of the nine stack-specific links go to the wrong guide: Next.js to the Vite/CRA guide, the Android SDK page to the Android UI Kit, the JavaScript SDK page to an overview rather than a guide, and the iOS page to the generic chooser. One-click suggestions on each. The root cause is that href and stack are independent props, so I have sketched a version of the component that derives one from the other on snippets/entry-point.mdx:19.

Non-blocking, raised inline on ui-kit/react/overview.mdx and web-shared/localize.mdx: the line competes with existing Get Started sections on two pages, displaces the AI Integration Quick Reference accordion on eight, and three of the 18 pages are orphans outside the nav. One more that has no good anchor: the set of 18 is a point-in-time Search Console snapshot, so it goes stale as rankings move and needs a recurring manual PR. A docs.json banner or a per-section import (the pattern the widget pages already use for V1UpgradeBody) would apply the line without a curated list.

Happy to re-review once the destination fixes and a decision on the tracking are in.

Comment thread snippets/entry-point.mdx Outdated
export const EntryPoint = ({ stack, href = "/chat-call", campaign = "docs" }) => (
<p>
New to CometChat?{' '}
<a href={`${href}?utm_source=docs&utm_medium=entry&utm_campaign=${campaign}`}>

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.

Blocking: this cannot count signups. The UTMs are attached to internal docs links (mostly /chat-call). chat-call.mdx does not forward query parameters, and its only link to the signup host (https://app.cometchat.com/, line 313) is untagged, so nothing from these parameters ever reaches app.cometchat.com. T-docs-entry.07 will read zero.

Two further points on the same line:

  • docs.json has no integrations block (analytics is {}), so unless tracking is injected some other way nothing records these parameters at all. If GA is added later, a UTM on an internal link starts a new session attributed to docs / entry and overwrites the reader's real acquisition source, so attribution gets worse, not better.
  • The URL is built with a bare ? and an unencoded campaign. An href that already has a query or a #fragment produces a malformed link (/chat-call#ui-kits?utm_source=... puts the UTMs inside the fragment). No current call site triggers it, but it is a shared component.

Suggested direction: decide what the line is meant to measure. If it is signups, tag the outbound Dashboard link on the destination page (or forward the params there) rather than the internal hop. If it is click-through on the docs line, a UTM is the wrong tool for an internal link; a plain link plus the existing page analytics, or an event, gives the number without skewing acquisition data.

Comment thread snippets/entry-point.mdx Outdated
keeps the space that JSX drops next to a tag.
*/}

export const EntryPoint = ({ stack, href = "/chat-call", campaign = "docs" }) => (

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.

href is a pure function of stack, but both are separate props, so the pair is hand-copied on nine pages and has already drifted (see the four call-site comments). Keeping the stack-to-guide map inside the component removes the prop that can disagree and lets pages pass only stack and campaign. Something like this (untested, keys illustrative):

export const EntryPoint = ({ stack, campaign }) => {
  const guides = {
    "React": "/ui-kit/react/integration-react",
    "Next.js": "/ui-kit/react/integration-nextjs",
    "React Native": "/ui-kit/react-native/react-native-cli-integration",
    "Android": "/ui-kit/android/getting-started",
    "iOS": "/ui-kit/ios/getting-started",
    "Android SDK": "/sdk/android/setup",
    "JavaScript SDK": "/sdk/javascript/setup-sdk",
  };
  const base = stack ? guides[stack] : "/chat-call";
  const sep = base.includes("?") ? "&" : "?";
  const href = `${base}${sep}utm_source=docs&utm_medium=entry&utm_campaign=${encodeURIComponent(campaign)}`;
  return (
    <p>
      New to CometChat?{' '}
      <a href={href}>{stack ? `Start with the ${stack} integration guide` : "Pick your stack and start building"}</a>.
    </p>
  );
};

Also worth making campaign required: all 18 call sites pass it, and the "docs" default means a page that forgets it compiles fine and silently reports an untraceable campaign instead of failing visibly.

Comment thread ui-kit/react/next-tab-based-chat.mdx Outdated

import { EntryPoint } from "/snippets/entry-point.mdx";

<EntryPoint stack="React" href="/ui-kit/react/integration-react" campaign="ui-kit" />

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 is the Next.js App Router guide, but the line sends readers to the Vite/CRA React guide. /ui-kit/react/integration-nextjs exists and is the one with the client-component and SSR steps they need.

Suggested change
<EntryPoint stack="React" href="/ui-kit/react/integration-react" campaign="ui-kit" />
<EntryPoint stack="Next.js" href="/ui-kit/react/integration-nextjs" campaign="ui-kit" />

Comment thread sdk/android/edit-message.mdx Outdated

import { EntryPoint } from "/snippets/entry-point.mdx";

<EntryPoint stack="Android" href="/ui-kit/android/getting-started" campaign="sdk" />

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 is an Android SDK page, but the link goes to the Android UI Kit getting-started. A developer who chose the SDK over the UI Kit is pushed into the other product line, and the sdk campaign now mixes clicks landing on two unrelated destinations (the JavaScript SDK page below points at the SDK). /sdk/android/setup is the SDK integration guide.

Suggested change
<EntryPoint stack="Android" href="/ui-kit/android/getting-started" campaign="sdk" />
<EntryPoint stack="Android SDK" href="/sdk/android/setup" campaign="sdk" />


import { EntryPoint } from "/snippets/entry-point.mdx";

<EntryPoint stack="JavaScript" href="/sdk/javascript/overview" campaign="sdk" />

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.

The link text promises "Start with the JavaScript integration guide" but /sdk/javascript/overview is the Overview page, not a guide. /sdk/javascript/setup-sdk is the integration page.

Suggested change
<EntryPoint stack="JavaScript" href="/sdk/javascript/overview" campaign="sdk" />
<EntryPoint stack="JavaScript SDK" href="/sdk/javascript/setup-sdk" campaign="sdk" />


import { EntryPoint } from "/snippets/entry-point.mdx";

<EntryPoint href="/chat-call" campaign="notifications" />

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.

Single-stack iOS page, yet it omits stack and points at the generic chooser. The snippet's own rule is to leave stack out only when the page has no single stack. /ui-kit/ios/getting-started exists.

Suggested change
<EntryPoint href="/chat-call" campaign="notifications" />
<EntryPoint stack="iOS" href="/ui-kit/ios/getting-started" campaign="notifications" />

Comment thread ui-kit/react/overview.mdx Outdated

import { EntryPoint } from "/snippets/entry-point.mdx";

<EntryPoint stack="React" href="/ui-kit/react/integration-react" campaign="ui-kit" />

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.

Non-blocking, but worth a look. This page already has a "Get Started / Pick your framework" card group (React.js, Next.js, React Router, Astro) at line 46. The new line above it hard-wires React.js, so a Next.js or Astro reader follows it to the Vite/CRA guide and never reaches the picker. rest-api/chat-apis.mdx similarly gains a CTA above its own ## Getting Started section.

Related: on this page and seven others (next-tab-based-chat, message-composer, message-bubble-styling, guide-new-chat, edit-message, ...) the first body element used to be the AI Integration Quick Reference accordion. It is now pushed below a marketing sentence, which is the first thing agents and copy-as-Markdown output see. Placing the entry point after the accordion on those pages keeps the structured summary first.

Comment thread web-shared/localize.mdx Outdated

import { EntryPoint } from "/snippets/entry-point.mdx";

<EntryPoint href="/chat-call" campaign="web-shared" />

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.

web-shared/* and ui-kit/kotlin/2.0/ui-components.mdx appear in no docs.json navigation group and have no redirects, so these are orphan legacy pages that happen to rank. web-shared as a utm_campaign names a section that does not exist on the site. Either drop the entry point from these three or, better, redirect them to their current equivalents, which is what the ranking is telling us to do.

More generally the campaign values are mixed granularity: mcp-server is one page, ui-kit is hundreds, and nothing identifies the originating page. If per-page insight is the goal (it is what justified picking these 18 by clicks), utm_content with the page slug, or the page path as the campaign, would carry it.

@raj-dubey1

Copy link
Copy Markdown
Contributor

Review: request changes

This PR is structurally safe and can't break the build, but one of its 18 pages won't get the line, and the UTM tags can't count signups. I also found a bigger problem that's already on main: five React pages have been frozen on live since 22 September.

P0: already on main, fix first

Five React pages fail MDX parsing, and live has stopped updating them. A bare <21 in a table cell (>=18 <21) is parsed as a JSX tag:

  • ui-kit/react/overview.mdx:16
  • ui-kit/react/integration-react.mdx:12
  • ui-kit/react/integration-nextjs.mdx:12
  • ui-kit/react/integration-astro.mdx:12
  • ui-kit/react/integration-react-router.mdx:12
Where What happens
Previews All five redirect (308) to Home on this PR's preview. overview and integration-react also land on Home on seven other PR previews.
Live All five return 200 but show content from before 412df50f (22 Sept).
Live peer deps ^4.1.9, plus dompurify as a peer dep
main peer deps ^4.2.0, with dompurify bundled
Checks Mintlify Deployment and link-rot both passed on this PR, so they don't catch this.

Another page from the same commit (components/conversations) did reach live, so this isn't a stalled deploy. The freeze mechanism is inferred from this behaviour, and I can't rule out these pages redirecting to Home on live after a full rebuild.

Fix: put the range in code formatting (`>=18 <21`) in a separate PR, merged before this one.

P1: should fix before merge

  1. ui-kit/react/overview won't get the line. Its preview shows Home, and live should stay frozen, so this is really 17 pages. The PR note says "Mintlify itself is more lenient… so the page builds", and the preview contradicts that. This is also the unnamed page from that note. All 4 React pages also link to integration-react, one of the frozen pages.
  2. The UTM tags can't count signups (snippets/entry-point.mdx:22). This confirms the earlier inline finding:
    • The only link from /chat-call to the dashboard (chat-call.mdx:313) has no tags.
    • docs.json has no analytics config, and the live page I checked has no GA, GTM or PostHog markers.
    • Dashboard-configured analytics could still exist, but nothing suggests it.
  3. The Android link sends SDK readers to the UI Kit (sdk/android/edit-message.mdx:9). This page has 879 of the 1,438 clicks (61%). The JavaScript SDK page stays in the SDK, so the two are inconsistent; /sdk/android/setup exists and is in the nav.
  4. The Next.js guide links to the React.js guide (ui-kit/react/next-tab-based-chat.mdx:9). The right target is /ui-kit/react/integration-nextjs, which is also frozen until the P0 fix lands.

P2: minor

  • notifications/ios-fcm-push-notifications.mdx:8: this iOS-only page gets the generic link. That follows the PR's mapping but contradicts the snippet's own comment.
  • rest-api/banned-users/unban.mdx:8: the line sits about 575px below the title on desktop and 640px on mobile, so it isn't "under the title". It's directly above "Error Guide" and before Authorizations, not at the bottom of the page.
  • Server rendering: on the three preview pages I checked, the line isn't in the server HTML, only in the browser after JavaScript runs. I don't know why, because the widget callout does render on the server.
  • .md output: the line splits across three lines, with a lone . on the last one, and exposes the UTM string to agents.
  • Three orphan pages: web-shared/localize, web-shared/reactions-configuration and ui-kit/kotlin/2.0/ui-components aren't in the nav.
  • snippets/entry-point.mdx:19-22: href and stack can drift apart, campaign isn't encoded and silently defaults, and an href with ? or # would produce a malformed link. No current page triggers the malformed link.
  • PR note errors: "Two things" lists three items, "two lines" per page is really four with blanks, "11 commits" behind is now 26, and "H1" appears in the snippet comment even though the PR note itself says these pages have no # heading.
  • validate-branch-name fails: docs-fix/ isn't an allowed prefix. I couldn't confirm the check is required, because the branch protection lookup returned 404.

Notes on the earlier reviews

  • The /docs prefix risk looks much lower than feared. On live, the widget snippet compiles to href /widget/migration but renders as /docs/widget/migration, so the prefix is added at render time. The entry line's link uses the same _components.a and renders with the same link class on the preview. A query string on a prefixed link is still untested, so click one link after merge.
  • The JavaScript link is not a real error. /sdk/javascript/overview describes itself as "Set up the CometChat JavaScript SDK", so I'd treat that suggestion as a preference, not a wrong link.

What passed

Check Result
Change size 19 files, +99/−0, matches the PR note
Merge Clean trial merge against current main; no overlapping files
Redirects and nav 0 missing redirects, 0 chained 404s, 0 dangling nav refs, so the build is safe
Link targets All 6 used, and all suggested alternatives, exist and are in the nav on the branch and main
Pages All 18 return 200 on live; 17 render on the preview
Rendering in a browser Checked on fundamentals/pin-message and rest-api/banned-users/unban; correct text and link, with the UTMs in the href
Broken links The 22 broken targets found are all in pages this PR doesn't touch
Skipped pages index and ai-agents do use mode: "custom", and none of the 18 do

Not verified:

  • The Search Console figures and the ranking of the top 20.
  • Any live click on the entry link, which isn't possible before merge.
  • Strict compile beyond the 18 pages and the 6 React pages I tested; the preview redirect scan only covered the first 60 ui-kit/react pages.

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>
@amitthacker-maker

Copy link
Copy Markdown
Author

Thanks all three of you. Pushed bb2fe8e4, which takes the structural points. Below is what changed, what I did not change and why, and an honest answer on the tracking.

First: the P0 is not this PR's, and it now has its own pull request

@raj-dubey1 found that five React pages have been frozen on live since 22 September. I verified it and it is real. It is already on main, so it is out of scope here and in #594, which should merge first.

Two things to add to his finding. The mechanism is no longer inferred: ui-kit/react/migration-overview carries the same >=18 <21 text inside backticks and builds and serves normally, which isolates the cause to the code span. And the blast radius is exactly five lines, confirmed by a repo-wide grep.

His line number for overview.mdx was right for this branch, line 16. On main it is line 12. Both correct, different refs.

Taken

href derived from stack (@siva-cometchat). You were right that this was the root cause rather than four separate mistakes. Pages now pass only stack and campaign. One change from your sketch: an unknown stack falls back to the chooser instead of throwing. A throw is a build failure, and a build failure in a table cell is what froze those five pages, so this component does not add that risk. I tested the href logic against all ten cases before wiring it up, including an unknown stack and a missing campaign.

campaign no longer defaults. A page that forgets it now produces a conspicuous utm_campaign=undefined rather than a plausible docs. Your point about silent failure stands.

Malformed-link guard. The query is now inserted before any fragment, so an href with a #fragment cannot put the parameters inside it.

Next.js destination. Confirmed by reading both: next-tab-based-chat says "Next.js (App Router)" and integration-nextjs is the App Router guide with the client-component and SSR steps. Fixed.

Android SDK destination. Fixed to /sdk/android/setup. Your reasoning about not pushing an SDK reader into the UI Kit is the principle I used for the iOS case below.

The AI accordion (@siva-cometchat, non-blocking). This turned out to be the most valuable point in the review, and it is an answer-engine problem rather than a layout one, so I treated it as blocking. On the six affected pages the entry line is now below the accordion.

I checked the served .md rather than reasoning about it, and the rendering was worse than described:

New to CometChat?
[Start with the React integration guide](/ui-kit/react/integration-react.md?utm_source=docs\&utm_medium=entry\&utm_campaign=ui-kit)
.

Three lines, a lone period, ampersands escaped as \&, and .md inserted before the query string. The sentence is now one line, which fixes the split and the stray period.

It is six pages, not eight: sdk/android/edit-message, ui-kit/android/guide-new-chat, ui-kit/react-native/message-bubble-styling, ui-kit/react/components/message-composer, ui-kit/react/next-tab-based-chat, ui-kit/react/overview.

Not taken, with reasons

The JavaScript SDK link stays at /sdk/javascript/overview. You and @raj-dubey1 disagreed here, so I read both pages rather than counting votes. overview is titled "Overview" but its body is the full walkthrough: get application keys, add the dependency, initialize, register and login, integrate UI Kits, integrate the widget. setup-sdk covers only install, import and initialize, and opens with a v3-to-v4 migration note that is noise for a new reader. The link promises an integration guide and overview delivers it. The title misleads; the content decides. I did rename the key to "JavaScript SDK" so the product line is explicit in the link text.

The iOS notifications page keeps the chooser. You are right that it contradicted the snippet's documented rule, but the rule is what was wrong. Platform alone cannot pick a destination, because iOS has both a UI Kit and an SDK and a notifications page is read by users of both. Sending them to the iOS UI Kit would repeat the mistake you correctly flagged on the Android SDK page. I sharpened the rule in the snippet comment instead of changing the call site.

So three destinations needed changing, not four.

The tracking, answered rather than worked around

It cannot count signups. Not "might not". Three independent breaks, each sufficient on its own, all verified:

  1. Nothing reads the parameters. docs.json has no integrations key and no analytics key at all. Live /chat-call returns zero occurrences for googletagmanager, gtag(, google-analytics, posthog, segment, analytics.js, mixpanel, amplitude, clarity.ms and hotjar.
  2. The tags sit on an internal hop, mostly /chat-call, which forwards nothing. No utm_, searchParams or location.search anywhere in chat-call.mdx.
  3. chat-call.mdx:313 is the only app.cometchat.com link in the file and it is untagged on live.

So T-docs-entry.07 would read zero, and the justification for the change as written does not hold.

@siva-cometchat's second-order point is the one that should drive the decision. If GA is added later, a UTM on an internal link starts a new session attributed to docs / entry and overwrites the reader's real acquisition source. These tags are not inert. They are a trap armed for whoever adds analytics, who will have no reason to look here.

I have left the tracking in place and built in one spot, so it comes out in a single edit. The decision is the docs owner's, not mine. My recommendation is to remove it from this PR and tag the outbound Dashboard link on the destination page instead, which is where a signup actually begins.

Still open, not addressed here

The curated list does not scale (@siva-cometchat). Your point that the set of 18 is a point-in-time Search Console snapshot needing a recurring manual PR is correct, and a docs.json banner or the per-section import the widget pages already use for V1UpgradeBody is a better design than this one. I have not changed the approach in this PR, but it is worth settling before the nine queued section branches land, because those cover about 2,628 files and would commit us to the curated list at scale.

Branch naming. docs-fix/ does fail validate-branch-name, because ^docs/ needs the slash straight after "docs". Neither of you could tell whether the check is required because the branch protection lookup 404s, and it does for me too. It is answerable another way: #583 merged on 29 October from docs-fix/link-decisions, and both branch-name workflows landed 30 September, so the check existed and did not block. It is advisory. #594 uses a conforming fix/ prefix.

The unban page placement and the three orphan pages are unchanged and still worth a decision. The orphans in particular: as you say, pages ranking while outside the nav is a signal to redirect them, not to decorate them.

Happy to take another look whenever you are.

🤖 Generated with Claude Code

@amitthacker-maker

Copy link
Copy Markdown
Author

One addition to the tracking section above, because my first check had a gap worth naming.

The task behind this change (T-docs-entry.07) specifies verifying a signup in HubSpot, via hs_analytics_source_data. My earlier list covered ten analytics vendors and HubSpot was not one of them, so "nothing reads the parameters" was not yet proven for the one tool the task actually names.

Checked it directly. On /docs/chat-call, /docs/ui-kit/react/overview and /docs/fundamentals/pin-message, all seven HubSpot markers return zero: hs-scripts, hsforms, hubspot, _hsq, hs-analytics, hsadspixel, hs-banner. There is no HubSpot tracker src anywhere on the docs host.

For contrast, www.cometchat.com does reference HubSpot, but only as component:"hubspot-form" blocks for "Contact our sales team". Those are embedded forms, not the tracking script, and hs-scripts and _hsq are both absent there too.

So the conclusion holds and is now specific rather than circumstantial: hs_analytics_source_data cannot show docs as the source for a reader who came through this line, because no HubSpot tracker observes the docs pageview in the first place. The signup also completes on app.cometchat.com, a different host, reached through an untagged link.

Nothing in the change above depends on this. I am noting it so the next person does not have to redo the check, and so "we track in HubSpot" does not look like an unexamined objection.

🤖 Generated with Claude Code

@ketanyekale

Copy link
Copy Markdown
Member

@siva-cometchat could you take another look? Amit pushed one commit since your review (Derive the entry link from the stack, and keep the AI summary first, 2 Nov), so here is what it does and does not cover against your two blockers.

Blocker 2 — wrong destinations: your structural fix was adopted, 2 of the 4 links are still open.

The href prop is gone and the stack-to-guide map now lives inside the component, essentially your sketch. The malformed-fragment case you raised is fixed too — the href builder splits on # and re-appends it after the query.

  • Next.js → /ui-kit/react/integration-nextjs — fixed
  • Android SDK page → /sdk/android/setup — fixed
  • JavaScript SDK page → still /sdk/javascript/overview, not /sdk/javascript/setup-sdk. Link text still reads "Start with the JavaScript SDK integration guide" while pointing at the Overview, which was your objection.
  • notifications/ios-fcm-push-notifications → still no stack, so still /chat-call. iOS was in your sketch's map but is not in the merged map, and neither is Flutter. The snippet's new comment reframes this as deliberate (a notifications page is read by both UI Kit and SDK users) rather than fixing it — worth deciding which reading you want, since the PR body still documents iOS → /ui-kit/ios/getting-started and Flutter → /ui-kit/flutter/getting-started, and an unmapped stack now falls back to the chooser silently.

Your campaign point is also still open: it has no default now, so a page that forgets it renders utm_campaign=undefined rather than failing visibly.

Blocker 1 — UTM tracking: not addressed in code. No integrations block was added and the outbound Dashboard link on the destination is still untagged. The PR description now carries a caveat agreeing the measurement is unproven until T-docs-entry.07 is run post-merge, so this is a decision for you rather than a diff to re-read.

No files were moved or renamed anywhere in the PR and docs.json is untouched, so there is no redirect or build exposure to re-check.

@amitthacker-maker

Copy link
Copy Markdown
Author

Superseded by #616. Please review that one instead.

This branch cannot merge from where it sits: validate-branch-name rejects the docs-fix/ prefix, and a pull request's head branch cannot be renamed in place. #616 is the same work on docs/entry-point-top-20, rebased onto current main from 273 commits behind.

Both blocking items from the review here are addressed there:

  • The two remaining wrong stack links are fixed. sdk/javascript/3.0/messaging-edit-message.mdx now points at /sdk/javascript/setup-sdk rather than an overview, and notifications/ios-fcm-push-notifications.mdx names stack="iOS" rather than falling back to the chooser. The guides map had no iOS entry at all, which is why that page could not name its stack.
  • The branch name now passes the check.

The non-blocking notes were taken where the fix was correctness rather than taste: ui-kit/react/overview.mdx drops its stack so it stops sending Next.js and Astro readers past that page's own framework picker, and the entry point is removed from the three orphan pages that were emitting utm_campaign=web-shared for a section that does not exist. The set goes from 18 pages to 15. rest-api/banned-users/unban is left as it is, since its rendering position is a judgement rather than a defect.

The UTM concern raised here is not resolved and is called out plainly in #616. It is a decision about whether the entry point ships without the measurement that justified it, not something a code change settles.

Leaving this open rather than closing it, so the review thread stays readable.

This branch was successfully deployed

1 active (outdated) deployment
staging — 1fd414e7 Deployed Oct 29, 2026 by mintlify[bot]
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.

6 participants