Skip to main content

Breadcrumb System Implementation Guide

This document provides comprehensive technical documentation for the dual breadcrumb system implementation in ClaudeLog, including swizzled components, CSS modules, and JavaScript interactions.

System Overview​

Dual Breadcrumb Architecture​

ClaudeLog implements a sophisticated dual breadcrumb system to handle both sidebar-integrated and orphaned pages:

  1. Automatic Breadcrumbs - Generated by Docusaurus for pages in sidebars.js
  2. Manual Breadcrumbs - Custom component for orphaned pages (FAQ details, etc.)

Why Both Systems Are Needed​

Problem: Docusaurus only generates automatic breadcrumbs for pages listed in sidebar configuration. Orphaned pages (like individual FAQ pages) don't appear in sidebars.js and therefore lack navigation context.

Solution: Manual breadcrumbs that visually match the automatic ones, creating seamless user experience across the entire site.

File Structure & Locations​

Core Components​

src/
├── theme/
│   └── DocBreadcrumbs/
│       ├── index.js          # Swizzled Docusaurus component
│       └── styles.module.css  # Swizzled component styles
├── components/
│   └── ManualBreadcrumb/
│       ├── index.js          # Custom manual breadcrumb component
│       └── styles.module.css  # Manual component styles
└── client/
    └── codeBlockClick.js     # JavaScript interactions & TOC management

CSS Hierarchy​

  1. Swizzled Component: src/theme/DocBreadcrumbs/styles.module.css

    • Controls automatic breadcrumbs
    • Handles global TOC visibility
    • Manages breadcrumb dividers for sidebar pages

  2. Manual Component: src/components/ManualBreadcrumb/styles.module.css

    • Controls manual breadcrumbs
    • Handles dividers for orphaned pages
    • Prevents external link arrows

  3. Global Styles: src/css/custom.css

    • General site-wide styles
    • Note: Breadcrumb-specific styles removed to avoid conflicts

Technical Implementation Details​

CSS Module Class Generation​

Docusaurus uses CSS modules that generate unique class names:

/* Source: styles.module.css */
.breadcrumbsContainer { ... }

/* Generated: */
.breadcrumbsContainer_VHDk  /* Swizzled component */
.breadcrumbsContainer_Alpn  /* Manual component */

Important: These class names change between builds and are not predictable.

Swizzled DocBreadcrumbs Component​

Location: src/theme/DocBreadcrumbs/index.js

Purpose: Override default Docusaurus breadcrumb behavior

Key Features:

  • Respects hide_breadcrumbs frontmatter flag
  • Identical to original except for conditional rendering
  • Maintains all original functionality

Modifications Made:

// Added condition to hide breadcrumbs when frontmatter specifies
if (options.hide_breadcrumbs) {
  return null;
}

Manual Breadcrumb Component​

Location: src/components/ManualBreadcrumb/index.js

Purpose: Provide breadcrumbs for orphaned pages

Usage:

import ManualBreadcrumb from '@site/src/components/ManualBreadcrumb';

<ManualBreadcrumb
  breadcrumbs={[
    { label: "Parent Section", href: "/parent" },
    { label: "Current Page", href: "/current-page" }
  ]}
  currentPage="Current Page"
/>

Key Features:

  • Pixel-perfect visual match to automatic breadcrumbs
  • Generates identical JSON-LD structured data
  • Prevents external link arrows
  • Includes custom divider styling

Recent Changes Documentation​

TOC Hiding Mechanism​

Problem: Needed to hide specific TOC collapsible elements (.tocCollapsible_ETCw, .tocCollapsible_IbkY)

Solution: Added global CSS rules to swizzled component:

/* src/theme/DocBreadcrumbs/styles.module.css */
:global(.tocCollapsible_ETCw),
:global(.tocCollapsible_IbkY) {
  display: none;
}

Why Here: Using :global() in the swizzled component ensures the rules apply site-wide while keeping them organized with related breadcrumb functionality.

Challenge: Both breadcrumb types needed consistent divider styling

Solution: Separate ::after rules for each component:

Automatic Breadcrumbs:

/* src/theme/DocBreadcrumbs/styles.module.css */
.breadcrumbsContainer::after {
  background: initial !important;
  border: 1px solid #333;
  content: "";
  display: block;
  margin: 1rem 0;
  width: 100%;
}

Manual Breadcrumbs:

/* src/components/ManualBreadcrumb/styles.module.css */
.breadcrumbsContainer::after {
  content: '';
  display: block;
  width: 100%;
  border: 1px solid #333333;
  background: none !important;
  background-color: transparent !important;
  margin: 1rem 0;
}

Note: Slight differences in implementation due to different CSS module contexts.

JavaScript Selector Updates​

Updated: src/client/codeBlockClick.js

Changes:

  1. TOC Button Selectors: Added support for multiple class variations

    const tocButton = document.querySelector('.tocCollapsibleButton_TO0P, .tocCollapsibleButton_p7nN');

  2. Timing Optimization: Reduced observer delay from 100ms to 10ms for faster response

  3. TOC Visibility Management: Enhanced handling of TOC display state

Implementation Context​

Original User Request​

The implementation was triggered by a specific user request to create a .breadcrumbsContainer_Alpn::after rule that matches the existing .breadcrumbsContainer_VHDk::after configuration exactly. This led to a comprehensive update of the breadcrumb system.

Manual Breadcrumb Identification​

Addition: Added 'manual-breadcrumbs' class to ManualBreadcrumb component

Purpose: Enables easy identification of manual vs automatic breadcrumbs for debugging

Implementation:

// src/components/ManualBreadcrumb/index.js
<nav
  className={clsx(
    ThemeClassNames.docs.docBreadcrumbs,
    'manual-breadcrumbs',  // Added for identification
    docStyles.breadcrumbsContainer,
    styles.breadcrumbsContainer
  )}
>

Debug Usage:

// In browser console
document.querySelector('.manual-breadcrumbs') ? 'Manual' : 'Automatic'

Property Differences Between Implementations​

While both breadcrumb components have similar divider styling, there are subtle but important differences:

Automatic Breadcrumbs (DocBreadcrumbs):

.breadcrumbsContainer::after {
  background: initial !important;
  border: 1px solid #333;
  content: "";
  display: block;
  margin: 1rem 0;
  width: 100%;
}

Manual Breadcrumbs (ManualBreadcrumb):

.breadcrumbsContainer::after {
  content: '';
  display: block;
  width: 100%;
  border: 1px solid #333333;
  background: none !important;
  background-color: transparent !important;
  margin: 1rem 0;
}

Key Differences:

  • Border Color: #333 vs #333333 (same visual result)
  • Background: initial vs none + transparent (different approaches, same result)
  • Property Order: Different organization due to different CSS module contexts

Cohesive Update Rationale​

All changes were made as part of a single cohesive update because:

  1. TOC Hiding: Needed to hide specific TOC elements that were interfering with breadcrumb functionality
  2. Breadcrumb Matching: User requested matching divider styles between automatic and manual breadcrumbs
  3. Code Cleanup: Opportunity to remove redundant styles and improve organization
  4. Performance: Timing optimizations for better user experience

Cleanup Process Details​

Removed from src/css/custom.css:

/* Removed - redundant TOC button styling */
.tocCollapsibleButton_TO0P {
  font-size: 0.9rem;
}

/* Removed - redundant TOC border styling */
.tocCollapsible_ETCw {
  border: 1px solid #333333;
  background: none !important;
  background-color: transparent !important;
  margin: 1rem 0 !important;
}

/* Removed - redundant breadcrumb divider */
.theme-doc-breadcrumbs::after {
  content: '';
  display: block;
  width: 100%;
  height: 1px;
  background-color: #333333;
  margin: 1rem 0;
}

Why Removed:

  • TOC Styles: Now properly handled in swizzled component with :global() selectors
  • Breadcrumb Divider: Caused conflicts with component-specific styling
  • Organization: Better separation of concerns with component-specific styles

Timing Optimization Details​

Change: Reduced MutationObserver delay from 100ms to 10ms

Location: src/client/codeBlockClick.js

Reason: Faster response time for TOC visibility management and code block interactions

Impact: Improved user experience without sacrificing reliability

Code:

// Before
}, 100);

// After
}, 10); // Reduced from 100ms to 10ms for faster response

Update Dependencies​

These changes work together as a system:

  1. TOC Hiding enables cleaner breadcrumb presentation
  2. Breadcrumb Dividers provide consistent visual separation
  3. JavaScript Updates ensure proper element detection
  4. Cleanup prevents style conflicts and redundancy

Breaking any one of these components may affect the others, so future modifications should consider the entire system.

Quirky Aspects & Gotchas​

CSS Module Class Names​

Issue: Class names like breadcrumbsContainer_VHDk are generated by Docusaurus and can change between builds.

Implication: Never hard-code these class names in JavaScript or global CSS.

Solution: Use CSS modules properly within components, or use :global() selectors when needed.

Dual Divider Styling​

Quirk: Both breadcrumb components have similar ::after rules but they're NOT redundant.

Explanation: CSS modules generate different class names, so each component needs its own styling:

  • breadcrumbsContainer_VHDk::after (automatic)
  • breadcrumbsContainer_Alpn::after (manual)

JavaScript Timing Issues​

Problem: TOC elements may not be immediately available in the DOM.

Solution: MutationObserver with reduced delay (10ms) for faster response while maintaining reliability.

Challenge: Markdown processing adds external link arrows to breadcrumb links.

Solution: Explicit CSS rules to prevent arrows:

.breadcrumbsContainer a::after {
  display: none !important;
}

Global Style Conflicts​

Issue: Global breadcrumb styles in custom.css conflicted with component-specific styles.

Resolution: Moved all breadcrumb-specific styles to respective components, keeping global styles minimal.

Troubleshooting Guide​

Common Issues​

1. Breadcrumbs Not Appearing

  • Check if page is in sidebars.js (should use automatic)
  • Verify hide_breadcrumbs: true in frontmatter for manual breadcrumbs
  • Confirm ManualBreadcrumb component is imported and used

2. Styling Issues

  • Inspect element to identify actual CSS class names
  • Check if styles are in correct component file
  • Verify CSS module import paths

3. Dividers Missing

  • Ensure ::after rules are present in component styles
  • Check for conflicting global styles
  • Verify CSS module class generation

4. TOC Not Hiding

  • Inspect actual TOC class names in browser
  • Update selectors in DocBreadcrumbs/styles.module.css
  • Check :global() selector syntax

Debug Steps​

1. Identify Breadcrumb Type

// In browser console
document.querySelector('.manual-breadcrumbs') ? 'Manual' : 'Automatic'

2. Inspect CSS Classes

// Find actual generated class names
document.querySelector('[class*="breadcrumbsContainer"]').className

3. Check TOC Classes

// Find TOC collapsible elements
document.querySelectorAll('[class*="tocCollapsible"]')

4. Verify Component Rendering

  • Check React DevTools for component hierarchy
  • Verify props are being passed correctly
  • Confirm conditional rendering logic

Future Maintenance​

Docusaurus Updates​

Watch For:

  • Changes to breadcrumb component structure
  • New CSS class naming conventions
  • Updates to swizzling mechanisms

Action Items:

  • Test breadcrumb functionality after major Docusaurus updates
  • Update swizzled component if base component changes
  • Monitor CSS class name changes

Potential Breaking Changes​

1. Swizzled Component Updates

  • Docusaurus may change base component structure
  • Manual merge may be required for updates

2. CSS Module Changes

  • Class naming conventions could change
  • Global selectors may need updates

3. JavaScript Selector Changes

  • TOC class names may evolve
  • Update selectors in codeBlockClick.js

Extending the System​

Adding New Breadcrumb Types:

  1. Create new component in src/components/
  2. Add corresponding CSS module
  3. Update JavaScript selectors if needed
  4. Document new patterns in this guide

Modifying Styling:

  1. Identify which component needs changes
  2. Update appropriate CSS module file
  3. Test both automatic and manual breadcrumbs
  4. Verify divider consistency

JavaScript Enhancements:

  1. Update codeBlockClick.js for new functionality
  2. Add appropriate selectors for new elements
  3. Maintain MutationObserver efficiency
  4. Test cross-browser compatibility

Testing Checklist​

When making changes to the breadcrumb system:

  • Test automatic breadcrumbs on sidebar pages
  • Test manual breadcrumbs on orphaned pages
  • Verify divider styling consistency
  • Check TOC hiding functionality
  • Test JavaScript interactions
  • Confirm responsive behavior
  • Validate structured data generation
  • Check external link arrow prevention
  • Test breadcrumb navigation functionality
  • Verify CSS module class generation

Conclusion​

The dual breadcrumb system provides seamless navigation across all page types while maintaining visual consistency. The swizzled component approach ensures compatibility with Docusaurus updates while providing the flexibility needed for custom breadcrumb implementations.

Key maintenance points:

  • Keep component styles separate and focused
  • Monitor CSS class name changes
  • Test thoroughly after Docusaurus updates
  • Document any new patterns or issues discovered

This system provides a robust foundation for breadcrumb navigation that scales with site growth and maintains consistency across all page types.

Last updated on