Skip to main content

Site Issue Resolutions

This document contains all issue resolutions for the Venture Orient AOS documentation site, including Algolia search customizations, breadcrumb fixes, sidebar modifications, and other site-wide issues.

Issue 1: Remove Blur Effect from Modal Overlay​

Issue​

Default Algolia search modal uses backdrop-filter: blur() which causes performance issues and doesn't match design requirements.

Cause​

Default Algolia CSS includes backdrop blur for aesthetic purposes, but this can cause lag on some devices and may not align with the desired visual style.

Resolution​

Replace blur with solid overlay in my-theme-v1.2.css:

/* MODAL CONTAINER & OVERLAY - NO BLUR */
.DocSearch-Container {
  background: rgba(0, 0, 0, 0.65) !important;
  /* backdrop-filter: blur(8px); <- REMOVED */
}

Issue 2: Center Search Bar in Navbar​

Issue​

Search bar appears off-center in the navbar, not properly aligned.

Cause​

Default positioning uses flex layout which doesn't guarantee center alignment when navbar has uneven content on sides.

Resolution​

Use absolute positioning to force center alignment:

/* Center search in navbar */
.navbar .navbarSearchContainer_Bca1,
.navbar [class*="navbarSearchContainer"] {
  position: absolute !important;
  left: 50% !important;
  transform: translateX(-50%) !important;
  width: 700px !important;
  max-width: 40vw !important;
  z-index: 10 !important;
}

Issue 3: Make Search Bar Wider​

Issue​

Search bar button appears too narrow in the navbar.

Cause​

Default button width is conservative to fit various layouts.

Resolution​

Increase minimum width and padding:

.DocSearch-Button {
  padding: 0 30px !important;
  height: 42px !important;
  min-width: 400px !important;
  width: 100% !important;
}

Issue 4: Remove Documentation Button from Navbar​

Issue​

"Documentation" button appears in navbar when it shouldn't be visible.

Cause​

Docusaurus auto-generates navbar items from folder structure.

Resolution​

Step 1: Add aggressive CSS hiding:

/* Hide Documentation button in navbar */
.navbar__link[href*="Documentation"],
.navbar__item a[href="/Documentation"],
.navbar__item a[href="Documentation"] {
  display: none !important;
  visibility: hidden !important;
  width: 0 !important;
  height: 0 !important;
  opacity: 0 !important;
  pointer-events: none !important;
}

/* Hide the parent li element */
.navbar__item:has(a[href*="Documentation"]) {
  display: none !important;
}

Step 2: Create swizzled NavbarItem component at /src/theme/NavbarItem/index.js:

import React, { useEffect } from 'react';
import NavbarItem from '@theme-original/NavbarItem';

export default function NavbarItemWrapper(props) {
  useEffect(() => {
    const hideDocButton = () => {
      const links = document.querySelectorAll('.navbar a');
      links.forEach(link => {
        if (link.textContent === 'Documentation' || 
            link.href?.includes('/Documentation')) {
          link.style.display = 'none';
          const parent = link.closest('.navbar__item');
          if (parent) parent.style.display = 'none';
        }
      });
    };
    
    hideDocButton();
    setTimeout(hideDocButton, 100);
  }, []);
  
  // Don't render if it's the Documentation link
  if (props.label === 'Documentation' || 
      props.to === '/Documentation' ||
      props.href === '/Documentation') {
    return null;
  }
  
  return <NavbarItem {...props} />;
}

Issue 5: Fix Navbar Not Stretching Full Width​

Issue​

Navbar appears glitched and doesn't stretch to the right edge of the page.

Cause​

Missing width and position properties on fixed navbar.

Resolution​

Ensure navbar uses full viewport width:

.navbar.navbar--fixed-top {
  position: fixed !important;
  top: 0 !important;
  left: 0 !important;
  right: 0 !important;
  width: 100% !important;
  z-index: 999 !important;
}

Issue 6: Remove Recent Searches on Modal Open​

Issue​

Recent searches appear when search modal opens, even with no input.

Cause​

Algolia stores and displays recent searches by default for user convenience.

Resolution​

CSS Solution:

/* Hide recent/suggested searches completely */
.DocSearch-StartScreen,
.DocSearch-StartScreen *,
.DocSearch-RecentSearches,
.DocSearch-FavoriteSearches,
[aria-label*="Recent"],
[aria-label*="recent"] {
  display: none !important;
  height: 0 !important;
  visibility: hidden !important;
  position: absolute !important;
  opacity: 0 !important;
}

JavaScript Component:

// In SearchBar component
<DocSearch
  // ... other props
  disableUserPersonalization={true}
  translations={{
    modal: {
      startScreen: {
        noRecentSearchesText: '',
        recentSearchesTitle: '',
        favoriteSearchesTitle: '',
      },
    },
  }}
/>

Issue​

Footer overlaps with the scrollbar, making it difficult to scroll to bottom items.

Cause​

Footer positioned inside scrollable container instead of at modal level.

Resolution​

Position footer at modal level, outside the scrollable area:

/* Modal with space for footer */
.DocSearch-Modal {
  padding-bottom: 40px !important;
  position: relative !important;
}

/* Footer positioned at modal bottom */
.DocSearch-Footer {
  position: absolute !important;
  bottom: 0 !important;
  left: 0 !important;
  right: 0 !important;
  z-index: 100 !important;
  height: 40px !important;
}

/* Dropdown without footer interference */
.DocSearch-Dropdown {
  max-height: calc(85vh - 120px) !important;
}

Issue 8: Remove Double Scrollbars​

Issue​

Both container and dropdown show scrollbars, creating a double scrollbar issue.

Cause​

Multiple nested containers have overflow:auto applied.

Resolution​

Only allow scrolling on the dropdown element:

/* Remove scrollbar from container */
.DocSearch-Dropdown-Container {
  overflow: hidden !important;
}

/* Hide container scrollbar */
.DocSearch-Dropdown-Container::-webkit-scrollbar {
  display: none !important;
  width: 0 !important;
}

/* Only dropdown should scroll */
.DocSearch-Dropdown {
  overflow-y: auto !important;
  overflow-x: hidden !important;
}

/* Style only dropdown scrollbar */
.DocSearch-Dropdown::-webkit-scrollbar {
  width: 14px !important;
}

Issue 9: Search Terms Not Highlighted​

Issue​

Search terms don't consistently highlight in all search results.

Cause​

Algolia's highlighting sometimes fails for partial matches or certain HTML structures.

Resolution​

CSS Force Highlighting:

/* Force highlighting everywhere */
.DocSearch-Hit * mark,
.DocSearch-Hit * em,
mark,
em.search-highlight {
  background: linear-gradient(135deg, #FFD700 0%, #FFC700 50%, #FFB700 100%) !important;
  color: #000000 !important;
  padding: 2px 4px !important;
  border-radius: 4px !important;
  font-weight: 800 !important;
  font-style: normal !important;
  display: inline-block !important;
}

JavaScript Fallback:

const highlightText = (text, query) => {
  if (!text || !query) return text;
  const escapedQuery = query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
  const regex = new RegExp(`(${escapedQuery})`, 'gi');
  return text.replace(regex, '<mark>$1</mark>');
};

Issue 10: Show Full Breadcrumbs with Sections​

Issue​

Breadcrumbs don't show the full path including the section where the match was found.

Cause​

Default breadcrumb display only shows page title, not the section hierarchy.

Resolution​

Build custom breadcrumbs in the SearchBar component:

const buildFullBreadcrumb = (hit) => {
  const parts = [];
  parts.push('🏠 Venture Orient AOS');
  
  // Add category
  if (category && categoryNames[category]) {
    const emoji = categoryEmojis[category] || '';
    parts.push(`${emoji} ${categoryNames[category]}`);
  }
  
  // Add page title (lvl2)
  if (hit.hierarchy?.lvl2) {
    parts.push(cleanDuplicateEmojis(hit.hierarchy.lvl2));
  }
  
  // Add section (lvl3 or lvl4)
  if (hit.hierarchy?.lvl3) {
    parts.push(cleanDuplicateEmojis(hit.hierarchy.lvl3));
  }
  
  return parts.join(' → ');
};

Issue 11: Remove Section Headers in Results​

Issue​

Headers like "Documentation" and "Owner's Manuals" appear between search results.

Cause​

Algolia groups results by source/category with headers.

Resolution​

Hide section headers with CSS:

/* Hide section headers */
.DocSearch-Hit-source {
  display: none !important;
  height: 0 !important;
  visibility: hidden !important;
}

Issue 12: Modal Not Auto-Expanding​

Issue​

Modal should start collapsed and expand smoothly when results appear.

Cause​

Fixed height on modal prevents dynamic sizing.

Resolution​

Use auto height with transitions:

/* Modal with auto height */
.DocSearch-Modal {
  height: auto !important;
  min-height: 120px !important;
  max-height: 85vh !important;
  transition: height 0.3s ease !important;
}

/* Dropdown expands with content */
.DocSearch-Dropdown {
  min-height: 0 !important;
  transition: all 0.3s ease !important;
}

/* Expand when results exist */
.DocSearch-Dropdown:has(.DocSearch-Hit) {
  min-height: 200px !important;
}

Issue 13: Fix Content Text Cutoff​

Issue​

Search result content text gets cut off mid-word.

Cause​

CSS line clamping without proper word wrapping.

Resolution​

Add word wrapping and hyphenation:

.my-theme-hit-content {
  display: -webkit-box !important;
  -webkit-line-clamp: 2 !important;
  -webkit-box-orient: vertical !important;
  overflow: hidden !important;
  text-overflow: ellipsis !important;
  word-wrap: break-word !important;
  hyphens: auto !important;
}

Issue 14: Modal Appears Under Navbar​

Issue​

When search modal opens, the navbar appears on top of it.

Cause​

Navbar has z-index of 999, modal container has lower or unset z-index.

Resolution​

Set higher z-index for modal elements:

/* Container higher than navbar */
.DocSearch-Container {
  z-index: 10000 !important; /* Higher than navbar (999) */
  position: fixed !important;
}

/* Modal higher than container */
.DocSearch-Modal {
  z-index: 10001 !important;
}

Issue 15: Search Shows Only 5-7 Results Instead of Hundreds​

Issue​

Despite having 1,020 records indexed with 462 matches for "email", search UI only displays 5-7 results.

Cause​

DocSearch component (from @docsearch/react) intentionally limits displayed results for better UX. By default, it shows only a few results per category/type (lvl1, lvl2, content, etc.).

Resolution​

Modify SearchBar component to increase result limits:

In /src/theme/SearchBar/index.js:

<DocSearch
  appId="WN5S4TF39F"
  apiKey="f804083657a46c2cf0e7e6723f589b56"
  indexName="documentation crawler for docs.ventureorient.com"
  
  // Key settings to show more results
  maxResultsPerGroup={50}  // Show up to 50 results per type
  
  searchParameters={{
    hitsPerPage: 200,      // Fetch up to 200 results total
    distinct: false,       // Don't limit to unique URLs
    facetFilters: [],      // Remove any filters
    attributesToRetrieve: ['*'],
    attributesToSnippet: ['content:100'],
    attributesToHighlight: ['*'],
  }}
  
  // ... rest of configuration
/>

Result​

  • Before: 5-7 results displayed
  • After: ~50 results displayed (Algolia's practical limit for good UX)
  • Index still has all 1,020 records for comprehensive search coverage

Note on Algolia Limits​

Algolia intentionally limits search results for performance:

  • Default search limit: 1,000 hits
  • DocSearch UI practical limit: ~50 results for optimal UX
  • For all records: Use browse method instead of search

Issue 14: Modal Appears Under Navbar​

Issue​

When search modal opens, the navbar appears on top of it.

Cause​

Navbar has z-index of 999, modal container has lower or unset z-index.

Resolution​

Set higher z-index for modal elements:

/* Container higher than navbar */
.DocSearch-Container {
  z-index: 10000 !important; /* Higher than navbar (999) */
  position: fixed !important;
}

/* Modal higher than container */
.DocSearch-Modal {
  z-index: 10001 !important;
}

Complete Theme Files​

File Structure​

/src/
  /css/
    /themes/
      my-theme-v1.2.css    # All custom styles
  /theme/
    /SearchBar/
      index.js             # Custom SearchBar component
    /NavbarItem/
      index.js             # Swizzled NavbarItem to hide Documentation

Testing Checklist​

After implementing changes:

  1. Restart server if JS changed: npm start
  2. Hard refresh if only CSS: Ctrl+F5
  3. Test each feature:
    • No blur on overlay
    • Centered, wider search bar
    • No Documentation button
    • Full-width navbar
    • No recent searches on open
    • Single scrollbar (no doubles)
    • Footer not overlapping scrollbar
    • Search terms highlighted
    • Full breadcrumbs with sections
    • No section headers in results
    • Modal expands/collapses properly
    • Content text not cut off
    • Modal appears above navbar
    • Correct emojis for all categories (especially 📋 for Owner's Manuals)

Version History​

  • v1.5: Added Issue 18 (Content text cutoff when highlighted) - January 21, 2025
  • v1.4: Updated Issue 16 with final mapping-free solution
  • v1.3: Added Issue 16 (Owner's Manuals emoji fix) and Issue 17 (hierarchy breadcrumbs)
  • v1.2: All 14 issues resolved and documented
  • Created: January 2025
  • Last Updated: January 2025

Issue 16: Wrong Emoji Displayed for Owner's Manuals Category​

Issue​

Owner's Manuals category showing 📚 (book) emoji instead of the correct 📋 (clipboard) emoji in search results.

Root Cause​

Hardcoded emoji mappings in the SearchBar component were overriding the correct emojis from Algolia's index.

Final Solution: Remove ALL Mappings​

Completely eliminated the need for any emoji mappings by trusting Algolia's index data.

Optimized SearchBar Component (/src/theme/SearchBar/index.js):​

// Build breadcrumb from Algolia hierarchy data ONLY
const buildFullBreadcrumb = (hit) => {
  const parts = [];
  
  // Always start with home
  if (hit.hierarchy?.lvl0) {
    parts.push(hit.hierarchy.lvl0);
  } else {
    parts.push('🏠 Venture Orient AOS');
  }
  
  // Add other levels if they exist
  if (hit.hierarchy?.lvl1 && hit.hierarchy.lvl1 !== hit.hierarchy.lvl0) {
    parts.push(hit.hierarchy.lvl1);
  }
  
  if (hit.hierarchy?.lvl2 && hit.hierarchy.lvl2 !== hit.hierarchy.lvl1) {
    parts.push(hit.hierarchy.lvl2);
  }
  
  if (hit.hierarchy?.lvl3 && hit.hierarchy.lvl3 !== hit.hierarchy.lvl2) {
    parts.push(hit.hierarchy.lvl3);
  }
  
  return parts.join(' → ');
};

// Get the best title from hierarchy
const getBestTitle = (hit) => {
  // Return the deepest hierarchy level available
  return hit.hierarchy?.lvl4 || 
         hit.hierarchy?.lvl3 || 
         hit.hierarchy?.lvl2 || 
         hit.hierarchy?.lvl1 || 
         'Search Result';
};

What Was Removed:​

  • ❌ All categoryEmojis mappings
  • ❌ All categoryNames mappings
  • ❌ The cleanDuplicateEmojis function
  • ❌ Any URL-based emoji logic
  • ❌ All hardcoded fallbacks

Set-and-Forget Flow:​

  1. Create page with emoji in title/frontmatter
  2. Algolia indexes the emoji automatically
  3. SearchBar displays exactly what's in the index

Test Verification:​

  • Created test page with 🦄 (unicorn) emoji - never used before
  • Algolia indexed it correctly
  • Search displayed the emoji without any mappings
  • Proved system is truly dynamic and mapping-free

Result:​

  • ✅ Zero maintenance - No mappings to update ever
  • ✅ Any emoji works - Use 🦄, 🌟, 🎪, whatever you want
  • ✅ Single source of truth - The page title IS the source
  • ✅ True set-and-forget - Just create pages, emojis work automatically

Issue 17: Full Breadcrumb Path Not Showing Complete Hierarchy​

Issue​

Search results don't show complete hierarchy path from root to page

Cause​

Crawler not properly building full hierarchy structure

Resolution​

Configure crawler to use proper hierarchy structure:

  • lvl0: Always "🏠 Venture Orient AOS" (root)
  • lvl1: Category with emoji (e.g., "📋 Owner's Manuals")
  • lvl2: Page title (for subpages)

Result: Full breadcrumb like: 🏠 Venture Orient AOS → 📋 Owner's Manuals → 📋 Documentation Naming Consistency

Issue 18: Content Text Gets Cut Off Vertically When Search Terms Are Highlighted​

Issue​

Search result content text gets cut off vertically (not horizontally) when search terms are highlighted. The highlighted text becomes bold and adds padding, increasing its height beyond the fixed container size.

Cause​

The content container had a fixed height (min-height: 44px and max-height: 44px) that couldn't accommodate highlighted text. When search terms are highlighted with:

  • font-weight: 800 (very bold)
  • padding: 2px 4px
  • display: inline-block

These styles add several pixels of height, causing the text to overflow and get cut off.

Resolution​

Make the content area responsive and reduce highlight impact:

Step 1: Make Content Container Responsive​

In my-theme-v1.2.css, update .my-theme-hit-content:

/* Fix for content cutoff in search results - NOW RESPONSIVE */
.my-theme-hit-content {
  font-size: 14px !important;
  color: rgba(0, 0, 0, 0.75) !important;
  line-height: 1.6 !important;
  display: -webkit-box !important;
  -webkit-line-clamp: 2 !important;
  -webkit-box-orient: vertical !important;
  overflow: hidden !important;
  text-overflow: ellipsis !important;
  min-height: 45px !important;  /* Base height for 2 lines */
  height: auto !important;      /* Allow dynamic height */
  max-height: 56px !important;  /* Increased to accommodate highlighted text */
  word-wrap: break-word !important;
  hyphens: auto !important;
  padding-bottom: 2px !important; /* Small buffer for highlights */
}

Step 2: Reduce Highlight Impact​

Update highlight styles to minimize vertical expansion:

mark,
.DocSearch-Hit mark,
.my-theme-hit-content mark {
  background: linear-gradient(135deg, #FFD700 0%, #FFC700 50%, #FFB700 100%) !important;
  color: #000000 !important;
  padding: 1px 3px !important;  /* Reduced from 2px 4px */
  border-radius: 3px !important;
  font-weight: 700 !important;  /* Reduced from 800 */
  box-shadow: 
    0 0 0 1px rgba(255, 199, 0, 0.3),
    0 1px 2px rgba(255, 199, 0, 0.2) !important;
  text-decoration: none !important;
  display: inline !important;  /* Changed from inline-block */
  text-shadow: none !important;  /* Removed text shadow */
  animation: highlightPulse 2s ease-in-out infinite;
  font-style: normal !important;
  line-height: inherit !important;  /* Inherit parent line-height */
  vertical-align: baseline !important;  /* Prevent vertical shift */
}

Step 3: Update Mobile Styles​

For mobile responsiveness:

@media (max-width: 768px) {
  .my-theme-hit-content {
    font-size: 13px !important;
    min-height: 42px !important;  /* Base height for mobile */
    height: auto !important;      /* Allow dynamic height */
    max-height: 52px !important;  /* Extra space for highlighted text */
    padding-bottom: 2px !important;
  }
}

Key Changes Summary​

  1. Container: Fixed height → Responsive (height: auto with increased max-height)
  2. Highlights: Reduced padding (2px → 1px), less bold (800 → 700), inline display
  3. Buffer: Added 11px extra max-height for highlight expansion
  4. Mobile: Similar responsive approach with adjusted dimensions

Result​

  • ✅ Content text no longer gets cut off when highlighted
  • ✅ Container dynamically expands to fit highlighted text
  • ✅ Maintains 2-line limit with proper ellipsis
  • ✅ Highlights are less bulky but still highly visible
  • ✅ Works on both desktop and mobile views

Issue 19: Search Results Prioritization - Sections Ranking Higher Than Folders​

Issue​

Search results showing incorrect priority order:

  1. Sections (H2/H3) appearing first
  2. Subpages appearing second
  3. Folder/Category pages appearing third
  4. Standalone pages appearing last

Expected order should be: Folders → Pages → Subpages → Sections

Root Cause​

The Algolia index had incorrect customRanking settings that were set to desc(weight.pageRank) instead of asc(weight.pageRank). This caused HIGHER weight values to rank first, inverting the intended priority.

Critical Discovery: initialIndexSettings in the crawler configuration only applies when an index is FIRST created. It does NOT update existing indices.

Resolution​

Step 1: Fix the Crawler Configuration​

Ensure the crawler uses asc (ascending) for weight ranking:

initialIndexSettings: {
  "documentation crawler for docs.ventureorient.com": {
    customRanking: [
      "asc(weight.pageRank)",  // LOWER values rank HIGHER
      "asc(weight.position)"
    ],
    // ... other settings
  }
}

Step 2: Delete and Recreate the Index​

Since initialIndexSettings only applies on first creation:

  1. Go to Algolia Dashboard
  2. Delete the existing index completely
  3. Run the crawler again - it will create a new index with correct settings
  4. Verify the settings in Configuration → Ranking and Sorting

Step 3: Implement Proper Weight System in Crawler​

The crawler assigns weights based on page type (LOWER weight = HIGHER priority):

// Weight assignment logic
if (pageType === "root") {
  baseWeight = 0;      // Highest priority
} else if (isCategoryPage) {
  baseWeight = 10;     // Folder/category pages - very high priority
} else if (pathParts.length === 1) {
  baseWeight = 50;     // Standalone pages - medium priority  
} else {
  baseWeight = 100;    // Subpages - lower priority
}

// Sections inherit parent weight + offset
// H2 sections: parent weight + 200
// H3 sections: parent weight + 300

Alternative Fix (Without Deleting Index)​

If you need to preserve the existing index, manually update settings in Algolia Dashboard:

  1. Go to Configuration → Ranking and Sorting
  2. Find Custom Ranking section
  3. Change from:
    • desc(weight.pageRank) ❌
    • desc(weight.level) ❌
  4. Change to:
    • asc(weight.pageRank) ✅ (ascending - lower values first)
    • asc(weight.level) ✅
    • asc(weight.position) ✅

Verification​

After fix, search results now correctly show:

  1. Folder/Category pages (weight: 10) - FIRST
  2. Standalone pages (weight: 50) - SECOND
  3. Subpages (weight: 100) - THIRD
  4. Sections (weight: 200+) - LAST

Key Learnings​

  • initialIndexSettings is a ONE-TIME configuration, not an update mechanism
  • Always verify customRanking uses asc for weight-based priority (lower = higher priority)
  • Deleting and recreating the index is the cleanest way to apply new settings
  • The Algolia Dashboard can override crawler settings, so always verify both are in sync