Documentation Configuration Guide

This guide explains how to configure the documentation system's search behavior, project scoping, and multi-project settings through the docs-folders-config.json file.

🎛️ Configuration Architecture

The documentation system uses a hierarchical configuration system that allows both global defaults and per-project overrides:

Global Configuration → Project-Specific Overrides → Built-in Defaults

📁 Configuration File Structure

Location

apps/docs-angular/src/assets/docs-folders-config.json

Basic Structure

{
  "globalConfig": {
    "search": { ... },
    "navigation": { ... },
    "ui": { ... }
  },
  "folders": [
    {
      "name": "GoGrab-Pulse",
      "isRoot": true,
      "config": { ... }  // Project-specific overrides
    }
  ]
}

🔍 Search Configuration

Global Search Settings

{
  "globalConfig": {
    "search": {
      "scopeToCurrentProject": true,
      "crossProjectSearch": false,
      "includePrivateInGlobalSearch": false,
      "maxResultsPerProject": 10,
      "enableProjectSwitchingFromSearch": true,
      "hasAccessToPublic": true
    }
  }
}

Configuration Properties Explained

scopeToCurrentProject (Primary Control)

Controls whether the system considers project boundaries during search operations.

• true: System considers project boundaries during search indexing and filtering
• false: System ignores project boundaries entirely and indexes all content

crossProjectSearch (Secondary Filter)

Controls whether to show results from other projects when scoping is enabled.

• true: Show results from all projects (when combined with scoping)
• false: Restrict results to current project only

includePrivateInGlobalSearch

Controls whether private/password-protected content appears in search results.

• true: Include private content in search results (if user has access)
• false: Exclude private content from search results

maxResultsPerProject

Maximum number of search results to show per project.

• Number: Limit results to this many items (e.g., 10)

enableProjectSwitchingFromSearch

Whether search results can trigger navigation to other projects.

• true: Allow clicking results to navigate to other projects
• false: Restrict navigation to current project only

hasAccessToPublic

Whether to show quick access to public documentation in the project switcher.

• true: Display "📖 Public Documentation" quick access link in project switcher
• false: Hide public documentation quick access option

🌍 UX Enhancement: When enabled, users can quickly navigate from private/restricted projects back to public documentation without manually typing URLs.

🎯 Search Behavior Matrix

Understanding how scopeToCurrentProject and crossProjectSearch work together:

Practical Examples

Cross-Project Discovery Mode

{
  "scopeToCurrentProject": true,
  "crossProjectSearch": true
}

• When: You want users to discover content across all projects
• Behavior: Indexes all content, shows all results
• UX: Search in GoGrab-Pulse shows results from public, other projects

Strict Project Isolation

{
  "scopeToCurrentProject": true,
  "crossProjectSearch": false
}

• When: Projects should be completely separate
• Behavior: Only indexes current project, only shows current project results
• UX: Search in GoGrab-Pulse only shows GoGrab-Pulse content

Performance Optimized Mode

{
  "scopeToCurrentProject": false,
  "crossProjectSearch": false
}

• When: You want fast project switching but focused results
• Behavior: Indexes all content once, filters results to current project
• UX: Fast project switching, focused search results

🏗️ Per-Project Configuration

Individual projects can override global settings by adding a config section that perfectly matches the global structure:

{
  "name": "GoGrab-Pulse",
  "path": "docs/english/GoGrab-Pulse",
  "language": "english",
  "isRoot": true,
  "password": "123456",
  "config": {
    "search": {
      "scopeToCurrentProject": true,
      "crossProjectSearch": false,        // Override: Disable cross-project search
      "includePrivateInGlobalSearch": false,
      "maxResultsPerProject": 5,          // Override: Fewer results
      "enableProjectSwitchingFromSearch": false,  // Override: Disable project switching
      "hasAccessToPublic": true           // Override: Enable public access
    },
    "navigation": {
      "enableBreadcrumbs": true,          // Override: Enable breadcrumbs
      "showProjectIcon": false,           // Override: Hide project icon
      "enableQuickSearch": true
    },
    "ui": {
      "theme": "dark",                    // Override: Use dark theme
      "enableAnimations": false,          // Override: Disable animations
      "compactMode": true                 // Override: Enable compact mode
    }
  }
}

Configuration Hierarchy

The system applies configurations in this priority order:

1. Project-Specific Config (Highest Priority)

   • Individual project config values (search, navigation, ui)
   • Only applies when user is in that specific project
   • Perfect match: Project config structure mirrors globalConfig exactly

2. Global Config (Fallback)

   • Values from globalConfig (search, navigation, ui)
   • Used when no project-specific override exists

3. Built-in Defaults (Last Resort)

   • Hardcoded sensible defaults in the code
   • Used when no configuration is found

Example: Mixed Configuration

{
  "globalConfig": {
    "search": {
      "scopeToCurrentProject": false,     // Global: Index all content
      "crossProjectSearch": true,         // Global: Show all results
      "maxResultsPerProject": 10
    }
  },
  "folders": [
    {
      "name": "GoGrab-Pulse",
      "isRoot": true,
      "config": {
        "search": {
          "crossProjectSearch": false     // Override: GoGrab-Pulse shows only own results
        },
        "ui": {
          "theme": "dark"                 // Override: Use dark theme for this project
        }
        // navigation not specified - inherits from global
      }
    },
    {
      "name": "public",
      // No config - uses global settings entirely
    }
  ]
}

Result:

• In GoGrab-Pulse: Shows only GoGrab-Pulse results with dark theme (project overrides)
• In Public: Shows all project results with default theme (global settings)

🎯 Perfect Structure Matching

Why Matching Structures?

The new configuration system uses identical structure between globalConfig and project-level config:

Benefits:

• ✅ Intuitive: Project config mirrors global config exactly
• ✅ Maintainable: Easy to understand what can be overridden
• ✅ Flexible: Override any part of the configuration tree
• ✅ Predictable: Same property paths at both levels

Before (Old searchConfig):

{
  "globalConfig": { "search": {...}, "navigation": {...}, "ui": {...} },
  "project": { "searchConfig": {...} }  // ❌ Only search, different structure
}

After (New config):

{
  "globalConfig": { "search": {...}, "navigation": {...}, "ui": {...} },
  "project": { "config": { "search": {...}, "navigation": {...}, "ui": {...} } }  // ✅ Perfect match
}

🧠 Understanding Indexing vs. Showing

Indexing (Building the Search Database)

• What: Process of reading and storing all searchable content in memory
• When: Happens during app load and when navigating between projects
• Performance: Slow operation (reads files, processes content)
• Controlled by: scopeToCurrentProject setting

Showing (Filtering Search Results)

• What: Process of filtering and displaying search results to the user
• When: Happens every time you type in the search box
• Performance: Fast operation (searches pre-built index)
• Controlled by: crossProjectSearch setting

Why This Separation Matters

Performance Optimization

{
  "scopeToCurrentProject": false,  // Index everything once
  "crossProjectSearch": false      // But only show current project results
}

• Benefit: Fast project switching (no re-indexing needed)
• Trade-off: Uses more memory but provides better UX

Security & Privacy

{
  "scopeToCurrentProject": false,  // Index all accessible content
  "crossProjectSearch": false      // But respect project boundaries
}

• Benefit: Content ready for authorized users, but isolated by default
• Use Case: Enterprise scenarios with mixed public/private content

🎨 Navigation Configuration

{
  "globalConfig": {
    "navigation": {
      "showProjectBreadcrumbs": true,
      "highlightCurrentProject": true
    }
  }
}

Navigation Properties

• showProjectBreadcrumbs: Show project context in navigation breadcrumbs
• highlightCurrentProject: Highlight the current project in navigation

🖥️ UI Configuration

{
  "globalConfig": {
    "ui": {
      "showProjectIndicator": true,
      "enableProjectSwitcher": true
    }
  }
}

UI Properties

• showProjectIndicator: Show current project name in the UI
• enableProjectSwitcher: Enable project switching functionality

🔧 Project Settings

Root Projects

Projects with "isRoot": true become standalone documentation sites:

{
  "name": "GoGrab-Pulse",
  "path": "docs/english/GoGrab-Pulse",
  "language": "english",
  "isRoot": true,           // Makes this a root project
  "password": "123456",     // Optional password protection
  "config": { ... }          // Optional per-project overrides (search, navigation, ui)
}

Password Protection

Projects can be password-protected:

{
  "name": "SecretProject",
  "isRoot": true,
  "password": "secret123"   // Users must enter this to access content
}

Deprecated: isPrivate

The isPrivate property is deprecated and ignored by the system. To make a project private, set a password on the project node. The scanner will automatically remove isPrivate and emit a warning during yarn docs:scan.

🌍 Public Documentation Access

The hasAccessToPublic feature provides seamless navigation between private/restricted projects and public documentation.

How It Works

When hasAccessToPublic is enabled for a project:

1. Project Switcher Enhancement: A special "📖 Public Documentation" option appears at the top of the project switcher
2. One-Click Access: Users can quickly navigate to public docs without manual URL entry
3. Language Awareness: Automatically navigates to the correct language version (/public or /es/public)
4. Visual Distinction: The public access option has a distinctive green styling to indicate its special nature

Use Cases

✅ Enable When:

• Users frequently switch between private projects and public documentation
• Project contains specialized content but users need access to general docs
• Improving overall user experience and navigation flow

❌ Disable When:

• Project should be completely isolated from public documentation
• Users should not have easy access to public content
• Project has its own comprehensive documentation

Example Configuration

{
  "name": "Private-Project",
  "isRoot": true,
  "password": "secret123",
  "searchConfig": {
    "hasAccessToPublic": true,  // Enable quick access
    "scopeToCurrentProject": true,
    "crossProjectSearch": false
  }
}

This creates a private project with password protection but allows quick access to public documentation for reference.

🚀 Best Practices

For Multi-Project Sites

{
  "globalConfig": {
    "search": {
      "scopeToCurrentProject": false,    // Fast switching
      "crossProjectSearch": true,        // Discovery across projects
      "maxResultsPerProject": 15
    }
  }
}

For Isolated Projects

{
  "globalConfig": {
    "search": {
      "scopeToCurrentProject": true,     // Project isolation
      "crossProjectSearch": false,       // No cross-contamination
      "maxResultsPerProject": 10
    }
  }
}

For Performance-Critical Sites

{
  "globalConfig": {
    "search": {
      "scopeToCurrentProject": false,    // Index once
      "crossProjectSearch": false,       // Filter results
      "maxResultsPerProject": 8          // Limit results
    }
  }
}

🛠️ Debugging Configuration

Console Logs to Watch

The system provides detailed logging for configuration debugging:

# Configuration Loading
🎯 Using search config: { scopeToCurrentProject: true, crossProjectSearch: false }

# Project Detection
🎯 Current project computed: "GoGrab-Pulse" from URL: /GoGrab-Pulse

# Indexing Behavior
🏗️ Building search index for project: "GoGrab-Pulse", language: en
🎯 Strict scoped indexing: Only indexing "GoGrab-Pulse" project content

# Search Filtering
🔍 Performing search for "app" in project: GoGrab-Pulse
🎯 Strict scoped search to project "GoGrab-Pulse": 15 indexed items

Common Issues

Search Not Working as Expected

1. Check current project detection: Look for 🎯 Current project computed logs
2. Verify configuration loading: Look for 🎯 Using search config logs
3. Check indexing behavior: Look for 🏗️ Building search index logs

Configuration Not Loading

1. Validate JSON syntax: Ensure docs-folders-config.json is valid JSON
2. Check file path: Verify file exists at correct location
3. Review browser network tab: Check if file loads successfully

🔮 Advanced Configuration

Dynamic Configuration

The system supports runtime configuration updates:

// In your component or service
const searchService = inject(SearchService);

// Update configuration and rebuild index
searchService.updateConfiguration({
  scopeToCurrentProject: false,
  crossProjectSearch: true
});

Environment-Specific Configuration

You can have different configurations for different environments:

{
  "globalConfig": {
    "search": {
      "scopeToCurrentProject": false,
      "crossProjectSearch": true,
      "maxResultsPerProject": 20    // More results in development
    }
  }
}

📞 Support

For configuration questions:

1. Check the console logs for detailed debugging information
2. Review the behavior matrix to understand setting combinations
3. Test different configurations in a development environment
4. Use the built-in debugging tools and logging

The configuration system is designed to be flexible and powerful while maintaining sensible defaults for most use cases! 🎯