Repository navigation
Docs: a one-line way to start on the top 18 docs pages - #585
amitthacker-maker wants to merge 3 commits into
Conversation
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>
Preview approval requiredThis pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
jitvarpatil
left a comment
There was a problem hiding this comment.
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
validate-branch-namefails.docs-fix/entry-point-top-20doesn'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 behindmain.
Worth a look (non-blocking)
-
rest-api/banned-users/unbandoesn'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. -
sdk/android/edit-messagesends 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/overviewexists, so please confirm this is what T-docs-entry.01 intended.
Please check after merge
- Click one link on www.cometchat.com. The preview has no
/docsbase 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 whosehrefis computed, so this pattern is unproven. If it misses, every link goes tocometchat.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
left a comment
There was a problem hiding this comment.
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:
- The UTM tagging cannot meet its stated goal. The parameters sit on internal links, the destination's signup link is untagged, and
docs.jsonhas 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 onsnippets/entry-point.mdx:22. - 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
hrefandstackare independent props, so I have sketched a version of the component that derives one from the other onsnippets/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.
| 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}`}> |
There was a problem hiding this comment.
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.jsonhas nointegrationsblock (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 todocs / entryand overwrites the reader's real acquisition source, so attribution gets worse, not better.- The URL is built with a bare
?and an unencodedcampaign. Anhrefthat already has a query or a#fragmentproduces 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.
| keeps the space that JSX drops next to a tag. | ||
| */} | ||
|
|
||
| export const EntryPoint = ({ stack, href = "/chat-call", campaign = "docs" }) => ( |
There was a problem hiding this comment.
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.
|
|
||
| import { EntryPoint } from "/snippets/entry-point.mdx"; | ||
|
|
||
| <EntryPoint stack="React" href="/ui-kit/react/integration-react" campaign="ui-kit" /> |
There was a problem hiding this comment.
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.
| <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" /> |
|
|
||
| import { EntryPoint } from "/snippets/entry-point.mdx"; | ||
|
|
||
| <EntryPoint stack="Android" href="/ui-kit/android/getting-started" campaign="sdk" /> |
There was a problem hiding this comment.
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.
| <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" /> |
There was a problem hiding this comment.
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.
| <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" /> |
There was a problem hiding this comment.
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.
| <EntryPoint href="/chat-call" campaign="notifications" /> | |
| <EntryPoint stack="iOS" href="/ui-kit/ios/getting-started" campaign="notifications" /> |
|
|
||
| import { EntryPoint } from "/snippets/entry-point.mdx"; | ||
|
|
||
| <EntryPoint stack="React" href="/ui-kit/react/integration-react" campaign="ui-kit" /> |
There was a problem hiding this comment.
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.
|
|
||
| import { EntryPoint } from "/snippets/entry-point.mdx"; | ||
|
|
||
| <EntryPoint href="/chat-call" campaign="web-shared" /> |
There was a problem hiding this comment.
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.
Review: request changesThis 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 P0: already on
|
| 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
ui-kit/react/overviewwon'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 tointegration-react, one of the frozen pages.- The UTM tags can't count signups (
snippets/entry-point.mdx:22). This confirms the earlier inline finding:- The only link from
/chat-callto the dashboard (chat-call.mdx:313) has no tags. docs.jsonhas 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.
- The only link from
- 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/setupexists and is in the nav. - 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.
.mdoutput: 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-configurationandui-kit/kotlin/2.0/ui-componentsaren't in the nav. snippets/entry-point.mdx:19-22:hrefandstackcan drift apart,campaignisn't encoded and silently defaults, and anhrefwith?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-namefails: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
/docsprefix risk looks much lower than feared. On live, the widget snippet compiles tohref/widget/migrationbut renders as/docs/widget/migration, so the prefix is added at render time. The entry line's link uses the same_components.aand renders with the samelinkclass 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/overviewdescribes 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/reactpages.
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>
|
Thanks all three of you. Pushed 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 Two things to add to his finding. The mechanism is no longer inferred: His line number for Taken
Malformed-link guard. The query is now inserted before any fragment, so an Next.js destination. Confirmed by reading both: Android SDK destination. Fixed to 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 Three lines, a lone period, ampersands escaped as It is six pages, not eight: Not taken, with reasonsThe JavaScript SDK link stays at 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 aroundIt cannot count signups. Not "might not". Three independent breaks, each sufficient on its own, all verified:
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 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 hereThe 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 Branch naming. The Happy to take another look whenever you are. 🤖 Generated with Claude Code |
|
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 Checked it directly. On For contrast, So the conclusion holds and is now specific rather than circumstantial: 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 |
|
@siva-cometchat could you take another look? Amit pushed one commit since your review ( Blocker 2 — wrong destinations: your structural fix was adopted, 2 of the 4 links are still open. The
Your Blocker 1 — UTM tracking: not addressed in code. No No files were moved or renamed anywhere in the PR and |
|
Superseded by #616. Please review that one instead. This branch cannot merge from where it sits: Both blocking items from the review here are addressed there:
The non-blocking notes were taken where the fix was correctness rather than taste: 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. |
What this changes
snippets/entry-point.mdx: one line, one link to the Start-here guide for the page's stack. The link carriesutm_source=docs,utm_medium=entryandutm_campaign=<docs section>.Skipped 2 of the 20:
index.mdxandai-agents.mdx. Both carrymode: "custom"in theirfrontmatter, which drops Mintlify's standard layout and the title it renders from
title:, sothere 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.
/ui-kit/react-native/react-native-cli-integration/ui-kit/react/integration-react/ui-kit/flutter/getting-started/ui-kit/ios/getting-started/ui-kit/android/getting-started/sdk/javascript/overview/chat-call, where a reader picks oneWhy 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-messageat 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
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.
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
mainhas moved 11 commits since, so compare againstthe merge-base rather than the tip:
That is 19 files, 99 insertions, 0 deletions.
git diff main..docs-fix/entry-point-top-20reports 139 files and 234 deletions, which is main's own later commits read backwards, not
anything this branch does. A trial merge against current
mainis clean: the files this branchtouches and the files
maingained since the merge-base do not overlap at all.