Optimizing Search and Navigation in MkDocs¶

Fast and intuitive navigation is crucial for documentation usability. Learn how to optimize search functionality and navigation in your MkDocs site for the best user experience.

Search Optimization¶

Configure Search Plugin¶

Start with a well-configured search plugin:

plugins:
  - search:
      lang: en
      separator: '[\s\-,:!=\[\]()/\"]+|(?!\b)(?=[A-Z][a-z])'
      pipeline:
        - stemmer
        - stopWordFilter

Search Features¶

Enable advanced search features:

theme:
  features:
    - search.suggest    # Show suggestions while typing
    - search.highlight  # Highlight search terms
    - search.share     # Share search via URL

Improve Search Results¶

1. Use Descriptive Titles¶

<!-- Bad -->
# Configuration

<!-- Good -->
# Database Configuration Guide

2. Add Search Metadata¶

---
search:
  boost: 2  # Boost this page in search results
tags:
  - configuration
  - database
  - setup
---

3. Include Search Keywords¶

<!-- Include common search terms -->
This guide covers database configuration,
including connection strings, pooling settings,
and performance tuning.

<!-- Alternative terms -->
Also known as: DB config, database setup, connection parameters

Enable instant loading for app-like performance:

theme:
  features:
    - navigation.instant          # Instant page loads
    - navigation.instant.prefetch # Prefetch on hover
    - navigation.tracking        # Update URL on scroll

nav:
  - Home: index.md
  - Getting Started:
    - Overview: getting-started/index.md  # Section landing pages
    - Installation: getting-started/install.md
    - Quick Start: getting-started/quickstart.md
  - User Guide:
    - guide/index.md  # Auto-expand sections
    - Basic Usage: guide/basics.md
    - Advanced Topics: guide/advanced.md

theme:
  features:
    - navigation.tabs        # Top-level sections as tabs
    - navigation.tabs.sticky # Keep tabs visible on scroll
    - navigation.sections    # Render sections as groups
    - navigation.expand     # Expand all sections by default
    - navigation.path       # Breadcrumb navigation
    - navigation.indexes    # Section index pages
    - navigation.top        # Back to top button

Performance Metrics¶

// Add to extra_javascript
window.addEventListener('load', function() {
  // Navigation timing
  const navStart = performance.timing.navigationStart;
  const loadComplete = performance.timing.loadEventEnd;
  const pageLoadTime = loadComplete - navStart;

  console.log(`Page load time: ${pageLoadTime}ms`);

  // Track navigation events
  document.addEventListener('click', function(e) {
    if (e.target.matches('a[href^="/"]')) {
      const startTime = performance.now();
      // Log navigation time
    }
  });
});

Search Performance¶

Monitor search performance:

// Track search usage
const searchInput = document.querySelector('.md-search__input');
let searchStartTime;

searchInput.addEventListener('focus', () => {
  searchStartTime = performance.now();
});

searchInput.addEventListener('blur', () => {
  const searchDuration = performance.now() - searchStartTime;
  console.log(`Search session duration: ${searchDuration}ms`);
});

Advanced Techniques¶

Custom Search Ranking¶

Create a custom search configuration:

// custom_search.js
document$.subscribe(() => {
  const search = document.querySelector(".md-search__form");
  if (search) {
    search.addEventListener("submit", (e) => {
      // Custom search logic
      const query = e.target.querySelector("input").value;
      // Boost certain pages based on query
    });
  }
});

Generate navigation based on content:

# hooks/navigation.py
def on_nav(nav, config, files):
    # Automatically generate navigation
    # from directory structure
    pass

Search Shortcuts¶

Add keyboard shortcuts:

// Keyboard shortcuts
document.addEventListener('keydown', (e) => {
  // Ctrl/Cmd + K for search
  if ((e.ctrlKey || e.metaKey) && e.key === 'k') {
    e.preventDefault();
    document.querySelector('.md-search__input').focus();
  }

  // / for search (when not in input)
  if (e.key === '/' && !e.target.matches('input, textarea')) {
    e.preventDefault();
    document.querySelector('.md-search__input').focus();
  }
});

Best Practices¶

1. Logical Information Architecture¶

docs/
├── getting-started/    # New users start here
│   ├── index.md       # Overview
│   ├── install.md     # Installation
│   └── quickstart.md  # First steps
├── guides/            # Task-oriented guides
│   ├── index.md  
│   └── ...
├── reference/         # Technical reference
│   ├── api/  
│   └── cli/  
└── troubleshooting/   # Problem-solving

2. Consistent Naming¶

Use clear, descriptive file names
Follow a naming convention
Avoid abbreviations
Use hyphens, not underscores

3. Search-Friendly Content¶

Write with search in mind:

# Error: Module Not Found

This error occurs when Python cannot find the specified module.

**Common causes:**
- Module not installed
- Incorrect import path
- Virtual environment issues

**Solutions:**
1. Install the module: `pip install module-name`
2. Check your import statement
3. Activate your virtual environment

Keep navigation shallow: - Maximum 3 levels deep - Use landing pages for sections - Group related content - Provide multiple paths to content

Troubleshooting¶

Search Not Working¶

Check search index:

mkdocs build --verbose
# Look for search index generation

Validate configuration:
```
plugins:
  - search  # Must be enabled
```
Check browser console:
```
// Look for JavaScript errors
```

Enable instant loading
Optimize images
Minimize JavaScript
Use CDN for assets

Conclusion¶

Optimized search and navigation significantly improve documentation usability. Focus on:

Fast search with relevant results
Intuitive navigation structure
Performance monitoring
User-friendly features

Remember: Users should find what they need within 3 clicks!

Further Resources¶

How do you optimize navigation in your docs? Share your tips! 🚀