Skip to content

docs: mechanical fixes from 2026-06 docs audit (links, frontmatter, descriptions, fence repair) - #395

Open
swapnil-cometchat wants to merge 9 commits into
mainfrom
docs/audit-mechanical-fixes
Open

docs: mechanical fixes from 2026-06 docs audit (links, frontmatter, descriptions, fence repair)#395
swapnil-cometchat wants to merge 9 commits into
mainfrom
docs/audit-mechanical-fixes

Conversation

@swapnil-cometchat

@swapnil-cometchat swapnil-cometchat commented Jun 14, 2026

Copy link
Copy Markdown
Contributor

Acts on the L0/L1 mechanical findings from the 2026-06-04 docs audit, re-validated against current main (the audit ran against a stale clone, so many counts were already obsolete). Each commit is one fix class and is independently reviewable.

What's fixed

Commit Class Result
.mdx-suffixed links Mintlify can't resolve them 18 links → extensionless absolute
i386+arm64 exclusion broke Apple Silicon simulators 7 RN/Flutter setup pages → exclude only i386
missing frontmatter filename-as-title, no meta desc 3 Angular ref/guide pages (snippet partials left as-is)
broken internal links version-drift (missing /v4/ segment) + others 648 → 1 broken links repaired
duplicate H1 body H1 dupes frontmatter title 2 ai-agents pages → ## Overview
garbled code fences bad migration mashed code onto fence lines, breaking rendering 5 SDK/agent pages, fence markers relocated (code untouched)
missing description no SEO/AEO meta description 55 pages (54 Android SDK v5 + webhooks) given tailored descriptions

Method / safety notes

  • All broken-link repairs only fired when exactly one candidate shared the source page's platform + version prefix; anchors preserved. 7 genuinely ambiguous/dead links were resolved by hand (see commit da2df29).
  • The audit's code_lang_missing (~2243 on a naive scan) turned out to be mostly a phantom — Mintlify treats post-language fence text as a title and supports flags like lines/{1-3}. The real defect was ~5 files with garbled fences (broken rendering), which are fixed here. A code-block-aware scan now reports 0 multiple-H1 files and 0 inline-closing fences.
  • The one remaining "broken link" is a /sdk/[relevant-section] template placeholder inside the abandoned .kiro/ orphan dir — out of scope.

Not in this PR

  • L2/L3 content rewrites (missing code samples, payload schemas, cross-links) — a separate editorial backlog.
  • Cosmetic "no syntax-highlighting language" on well-formed blocks — low value, inference-risky.

🤖 Generated with Claude Code
Kiro Agent and others added 9 commits June 15, 2026 02:16
Kiro Agent @claude
docs: fix .mdx-suffixed relative links to extensionless absolute paths
2991108 
Mintlify does not resolve relative links that include the .mdx extension.
Rewrites 18 links across 9 Angular UI Kit pages to absolute extensionless
slugs, and corrects one link pointing at a non-existent message-composer
page to cometchat-message-composer.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Kiro Agent @claude
docs: exclude only i386 (not arm64) from iOS simulator builds
838d0ff 
Excluding arm64 from EXCLUDED_ARCHS breaks native simulator builds on
Apple Silicon Macs (now effectively all dev machines). Switch the 7
RN/Flutter setup samples to exclude only the dead i386 arch — which the
pages' own Warning callouts already recommended — and reword the callout
to warn against re-adding arm64.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Kiro Agent @claude
docs: add frontmatter to 3 Angular UIKit reference/guide pages
6afad2a 
rich-text-editor-service, formatter-config-service, and rich-text-formatting
had no YAML frontmatter, so Mintlify fell back to the filename as title and
produced no meta description. Add title + description and drop the now-duplicate
body H1. (snippets/ partials intentionally keep no frontmatter.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Kiro Agent @claude
docs: repair 620 intra-version broken links (missing version segment)
fa1842c 
Legacy UI Kit pages link to sibling pages without the version segment
(e.g. a /ui-kit/angular/v4/ page links to /ui-kit/angular/avatar instead
of /ui-kit/angular/v4/avatar). Repoint each to the same-platform,
same-version target that actually exists; anchors preserved. Resolver only
applied a fix when exactly one candidate shared the source's platform AND
version prefix.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Kiro Agent @claude
docs: fix remaining unambiguous broken links
3ea8b9b 
- angular search/search-messages: point bare /accessibility, /events,
  /integration at their /ui-kit/angular/ pages
- ios v4 conversations-with-messages: fix case-sensitive /Contacts -> /contacts
- calls flutter setup: point calling-integration link at the v5 page that exists
- react v7 components-overview & guide-message-privately: drop stale cometchat-
  prefix (users/groups/group-members) and fix ai-assistant -> ai-assistant-chat

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Kiro Agent @claude
docs: resolve final 7 broken links with judgment calls
da2df29 
- react/react-native/v6 campaigns: point 'UI Kit integration' at the
  in-version UI Kit overview (the getting-started hub)
- flutter v4/v5 message-template: 'Message Categories' -> v4 SDK structure
  page (v4) and messaging-overview (v5, no structure page exists in current SDK)
- react v7 components-overview: unlink CallButtons (v7 component page not yet
  authored) with a 'coming soon' note instead of a 404
- sdk/android ai-chatbots: bare /ai-chatbots has no page (/overview is a legacy
  external redirect) -> point to /ai-chatbots/custom-bots

Remaining broken link is a template placeholder in the abandoned .kiro/ dir.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Kiro Agent @claude
docs: demote duplicate body H1 to H2 on two ai-agents pages
e699d7f 
sdk/flutter/ai-agents and sdk/android/v5/ai-agents each had a body
'# AI Agents Overview' H1 that duplicated the frontmatter title (Mintlify
renders the title as the page H1). Demote to '## Overview'. Code-block-aware
scan now reports zero multiple-H1 files.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Kiro Agent @claude
docs: repair garbled code fences that broke rendering in 5 SDK/agent …
1f6982f 
…pages

A bad migration mashed the opening fence + code + closing fence onto shared
lines (e.g. '```javascript let limit = 30,' ... '.build(); ```'). Because the
closing ``` was not on its own line, CommonMark never closed the block, so it
swallowed the following <Tab>/<Tabs> markup and prose until the next fence.

Relocate the fence markers onto their own lines (code text untouched) in
retrieve-conversations, receive-message, retrieve-group-members, block-users,
and mastra-runtime-context. All fence counts now balanced; zero inline-closing
fences remain.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Kiro Agent @claude
docs: add SEO/AEO meta descriptions to 55 pages missing one
3682bfe 
54 Android SDK v5 pages plus fundamentals/webhooks-overview had no
frontmatter description, so they shipped with no meta description for
search/AI answer engines. Add a tailored 60-160 char description to each,
derived from the page's title and intro. (3 link/ nav stubs intentionally
left minimal.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mintlify

mintlify Bot commented Jun 14, 2026 •
edited
Loading

Copy link
Copy Markdown

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

Project Status Preview Updated (UTC)
cometchat 🟢 Ready View Preview Jun 14, 2026, 9:27 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

1 participant

@swapnil-cometchat