fix: ensure unique TOC slugs for repeated headings(Examples)

[Sourya07]

Description
• Fixes an issue where multiple headings with the same name (e.g: Examples) generated identical slugs in the TOC.
• This caused incorrect navigation behavior in the right sidebar (TOC), especially on pages like the Numbers Style Guide, where several “Examples” sections exist
• The fix appends a numeric suffix to duplicate headings (based on seen count), ensuring each TOC entry has a unique slugWithATag
• This resolves broken anchor navigation and scrollspy highlighting.

fixes this ->#4591

     What was happening
->	Every repeated “Examples” heading generated the same slug (#examples).
•	TOC links all pointed to the same section.
->	Scrollspy could not correctly highlight active sections.
•	Users couldn’t navigate to specific example blocks.

What this PR changes

•	When a heading has a seen value greater than 0 a suffix is added ->
•	examples
•	examples-1
•	examples-2
•	examples-3

Summary by CodeRabbit

• New Features

  • TOC items can include an optional "seen" value; anchors and links append a suffix when present to distinguish repeated headings and improve anchor uniqueness.

• Bug Fixes

  • Table of Contents anchor generation and link resolution are more consistent for items with and without the "seen" value, fixing duplicate-anchor issues.

• Style

  • Minor responsive and class-name adjustments to improve TOC layout, alignment and visual behavior when sections are opened.

[netlify]

✅ Deploy Preview for asyncapi-website ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	e32fa6e
🔍 Latest deploy log	https://app.netlify.com/projects/asyncapi-website/deploys/693557afba349300082a8418
😎 Deploy Preview	https://deploy-preview-4593--asyncapi-website.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Walkthrough

TOC item interface now accepts an optional seen?: number. Slug generation computes a sanitized base from item.content and conditionally appends -<seen> when item.seen > 0. Minor className and heading composition formatting refactor in components/TOC.tsx.

Changes

Cohort / File(s)	Summary
TOC slug & rendering components/TOC.tsx	Added optional seen?: number to TOC item type; compute baseSlug from item.content (sanitize, hyphenate, lowercase), then set slugWithATag via an IIFE that appends -<seen> when item.seen > 0; updated className/heading string composition and responsive breakpoint classes.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant UI as TOC Component
  participant Item as TOC Item
  participant Slug as Slug Generator
  participant DOM as Anchor/Heading

  UI->>Item: read item.content and item.seen
  Note right of Slug `#DDEBF7`: sanitize content\n(strip special chars, spaces→hyphens, lowercase)
  Item->>Slug: provide content
  Slug-->>Slug: compute baseSlug
  alt item.seen > 0
    Slug-->>Slug: append "-<seen>" suffix
  end
  Slug->>DOM: emit `slugWithATag` for id/href
  DOM->>UI: render anchor/heading with computed slug

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Inspect regex/normalization used to sanitize item.content.
• Verify seen suffix logic only applies when item.seen > 0 and maintains uniqueness.
• Confirm className/heading refactor preserves responsive behavior.

Possibly related PRs

• fix: toc links in the blogs #3562 — overlaps in components/TOC.tsx slug handling and fallback behavior for slugWithATag.
• fix: remove extra symbols from fragment URLs #3634 — touches slug sanitization/regex used when generating TOC anchors.

Suggested labels

ready-to-merge

Suggested reviewers

• princerajpoot20
• derberg
• anshgoyalevil
• devilkiller-ag
• akshatnema
• sambhavgupta0705

Poem

🐰 I hopped through the TOC, tidy and spry,
I carved clean slugs as the headings fly by.
A little -seen tail for the ones I recall,
Anchors now neat — I bounded the hall. ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Title check	✅ Passed	The title clearly and specifically describes the main change: fixing duplicate TOC slugs for repeated headings by ensuring uniqueness.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[asyncapi-bot]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🔴 Performance	43
🟢 Accessibility	98
🟢 Best practices	92
🟢 SEO	100
🔴 PWA	33

Lighthouse ran on https://deploy-preview-4593--asyncapi-website.netlify.app/

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

components/TOC.tsx (1)

41-53: Slug uniqueness logic is solid; consider typing seen and extracting a helper

The new slugWithATag logic correctly ensures uniqueness by appending -<seen> when the item has been seen before, which should address the duplicate TOC anchor issue for repeated headings.

Two small improvements you might consider:

• Type safety: instead of (item as any).seen, extend the TOC item shape to include an optional seen?: number and drop the any cast:

-  toc: {
-    lvl: number;
-    content: string;
-    slug: string;
-  }[];
+  toc: {
+    lvl: number;
+    content: string;
+    slug: string;
+    seen?: number;
+  }[];

and then:

-        if (typeof (item as any).seen === 'number' && (item as any).seen > 0) {
-          return `${base}-${(item as any).seen}`;
-        }
+        if (typeof item.seen === 'number' && item.seen > 0) {
+          return `${base}-${item.seen}`;
+        }

• Reuse/consistency: if the same slugging rules exist wherever the actual heading ids are generated, extracting this IIFE into a shared helper (e.g., slugFromHeading(content, seen?)) would reduce the risk of the TOC getting out of sync with the DOM IDs over time.

Overall, the behavior change looks good; these are just type-safety and maintainability tweaks.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5bfca09 and 6cd9f2c.

📒 Files selected for processing (1)

• components/TOC.tsx (3 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2024-10-11T10:46:58.882Z

Learnt from: akshatnema
Repo: asyncapi/website PR: 3262
File: components/Avatar.tsx:35-44
Timestamp: 2024-10-11T10:46:58.882Z
Learning: In Next.js, when avoiding nested `<a>` tags due to hydration issues, use accessible non-link elements like `<button>` or `<span>` with appropriate roles, `tabIndex`, and event handlers to maintain accessibility and SEO.

Applied to files:

• components/TOC.tsx

⏰ Context from checks skipped due to timeout of 180000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: cypress-run
• GitHub Check: Test NodeJS PR - macos-13
• GitHub Check: Test NodeJS PR - windows-latest
• GitHub Check: Lighthouse CI

🔇 Additional comments (1)

components/TOC.tsx (1)

68-72: Heading className formatting change is safe

The updated template string for the <h5> classes preserves the previous Tailwind behavior (only whitespace/newline changes plus the same conditional xl vs lg classes). No functional issues here.

[Sourya07]

Hi @princerajpoot20,
Whenever you get time, please review this PR. Thank you! 🙏

[princerajpoot20]

@Sourya07 Can you please have a look at the nitpick comments mentioned above

[Sourya07]

@princerajpoot20
I’ve fixed the seen?: number; issue and resolved the Prettier formatting errors.

[princerajpoot20]

Added a small suggestion. The rest looks good.

[Sourya07]

Added a small suggestion. The rest looks good.

Now it has been fixed .
Thank you for reviewing ☺️

[princerajpoot20]

Pipeline is failing. Please have a look.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (a056c20) to head (e32fa6e).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff            @@
##            master     #4593   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           22        22           
  Lines          799       799           
  Branches       146       146           
=========================================
  Hits           799       799           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Sourya07]

Pipeline is failing. Please have a look.

All the checks has been cleared

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

components/TOC.tsx (2)

7-15: Document and stabilize the seen semantics on TOC items

The seen?: number addition is a clean way to support disambiguating duplicate headings, and the rest of the code treats it as an occurrence counter (> 0 meaning “duplicate”). To make this easier to use correctly from callers, consider briefly documenting the expected semantics (e.g., “0 for first occurrence, 1 for second, …”) where the TOC items are constructed or in a short JSDoc on the interface.

This is non-blocking but will help future maintainers wire the counter consistently.

---

60-63: Tighten twMerge usage to avoid "undefined" classes and improve readability

Using twMerge here is fine, but interpolating className directly into a template string can still produce a literal "undefined" class when className is not provided. It also makes it a bit harder to see which classes are conditional vs static.

Consider restructuring to pass arguments directly to twMerge, and guarding className separately:

-    <div
-      className={twMerge(
-        `${className} ${tocItems.length ? '' : 'hidden'} 
-      ${cssBreakingPoint === 'xl' ? 'xl:block' : 'lg:block'} md:top-24 md:max-h-(screen-14) mb-4 z-20`
-      )}
+    <div
+      className={twMerge(
+        className,
+        tocItems.length ? '' : 'hidden',
+        cssBreakingPoint === 'xl' ? 'xl:block' : 'lg:block',
+        'md:top-24 md:max-h-(screen-14) mb-4 z-20'
+      )}

You can apply the same pattern to the <h5> className block to keep conditional bits clearer and avoid accidental "undefined" there as well. This is a readability/robustness improvement, not a blocker.

Also applies to: 71-77

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8666f79 and febb22e.

📒 Files selected for processing (1)

• components/TOC.tsx (3 hunks)

🧰 Additional context used

🧠 Learnings (4)

📓 Common learnings

Learnt from: asyncapi-bot
Repo: asyncapi/website PR: 0
File: :0-0
Timestamp: 2025-02-18T12:07:42.211Z
Learning: The following PR commands are supported in the asyncapi/website repository:
- `/please-take-a-look` or `/ptal`: Requests attention from reviewers who haven't reviewed the PR
- `/ready-to-merge` or `/rtm`: Triggers automerge when all conditions are met
- `/do-not-merge` or `/dnm`: Blocks automerge even if all conditions are met
- `/autoupdate` or `/au`: Adds autoupdate label to keep PR in sync with target branch
- `/update` or `/u`: One-time update of PR with latest changes from target branch

📚 Learning: 2024-10-11T07:38:35.745Z

Learnt from: akshatnema
Repo: asyncapi/website PR: 3262
File: components/newsroom/FeaturedBlogPost.tsx:90-92
Timestamp: 2024-10-11T07:38:35.745Z
Learning: In Next.js, nested `<a>` tags cause hydration issues due to invalid HTML. To fix this, avoid nesting `<a>` tags by replacing inner `<a>` tags with non-interactive elements like `<span>`, and use click handlers to maintain interactivity if needed.

Applied to files:

• components/TOC.tsx

📚 Learning: 2024-10-11T10:46:58.882Z

Learnt from: akshatnema
Repo: asyncapi/website PR: 3262
File: components/Avatar.tsx:35-44
Timestamp: 2024-10-11T10:46:58.882Z
Learning: In Next.js, when avoiding nested `<a>` tags due to hydration issues, use accessible non-link elements like `<button>` or `<span>` with appropriate roles, `tabIndex`, and event handlers to maintain accessibility and SEO.

Applied to files:

• components/TOC.tsx

📚 Learning: 2024-10-11T11:32:30.226Z

Learnt from: akshatnema
Repo: asyncapi/website PR: 3262
File: components/navigation/BlogPostItem.tsx:95-119
Timestamp: 2024-10-11T11:32:30.226Z
Learning: In the `BlogPostItem` component (`components/navigation/BlogPostItem.tsx`), nesting `<a>` tags inside the parent `Link` component leads to hydration issues; therefore, we should avoid nesting `<a>` tags inside `Link` components in this component.

Applied to files:

• components/TOC.tsx

⏰ Context from checks skipped due to timeout of 180000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Test NodeJS PR - windows-latest

🔇 Additional comments (1)

components/TOC.tsx (1)

31-56: Slug generation with seen suffix looks correct and robust

The minLevel calculation and tocItems mapping look fine, and the new slugWithATag IIFE:

• Builds a normalized base slug from item.content.
• Appends -seen only when seen is a number and strictly greater than 0.
• Leaves the first occurrence unsuffixed, which matches the examples → examples-1 → examples-2 behavior described in the PR.

The explicit typeof item.seen === 'number' guard also makes this resilient to any unexpected runtime data.

No changes needed here from my side.

[princerajpoot20]

LGTM!

[princerajpoot20]

@sambhavgupta0705 PTAL

[Sourya07]

Thanks for reviewing this, @princerajpoot20 and @sambhavgupta0705 🙏
Really appreciate the help!

[Sourya07]

Hey @sambhavgupta0705,
Whenever you get some time, could you please take a look at this PR?

[Sourya07]

@princerajpoot20
@asyncapi-bot @dalelane
can you guys please review this

[Sourya07]

@princerajpoot20
@derberg
have a look on this pr .

[princerajpoot20]

/rtm

[Sourya07]

@princerajpoot20 thanks for looking on this ☺️