Search

Mordoc automatically generates a powerful client-side search index for your documentation, allowing users to quickly find content across all pages. No configuration or external services required.

How Search Works

Search is automatically enabled for every Mordoc site:

1. Build Time: Search index is generated during npm run build
2. Client-Side: Search runs entirely in the browser
3. Fast Results: Instant search as you type
4. Full Content: Searches all markdown content, headings, and text
5. No Backend: No servers or external services needed

Search Features

Full-Text Search

Searches across:

• Page titles
• Headings (all levels)
• Body content
• Code comments (configurable)
• Alt text from images

Smart Ranking

Results are ranked by:

• Relevance to search query
• Heading matches (higher weight)
• Title matches (highest weight)
• Content matches
• Proximity of search terms

Live Results

• Results appear as you type
• No "search" button needed
• Instant filtering
• Keyboard navigation supported

Using Search

Search Bar Location

By default, the search bar appears:

• Desktop: Top right of navigation bar
• Mobile: Accessible via search icon

Keyboard Shortcuts

Search Query Syntax

Basic search:

authentication

Multiple words (AND):

api authentication

Phrase search:

"getting started"

Exclude terms:

api -deprecated

Configuration

Customize search behavior through configuration.

Edit config/styles/main.json:

{
  "search": {
    "enabled": true,
    "placeholder": "Search documentation...",
    "hotkey": "/",
    "maxResults": 10,
    "excerptLength": 150,
    "highlightMatches": true
  }
}

Configuration Properties

Disable Search

To disable search completely:

{
  "search": {
    "enabled": false
  }
}

Custom Placeholder

{
  "search": {
    "placeholder": "What are you looking for?"
  }
}

Adjust Results Count

{
  "search": {
    "maxResults": 15
  }
}

Styling Search

Customize search appearance:

{
  "search": {
    "inputBackground": "#ffffff",
    "inputBorder": "#d1d5db",
    "inputText": "#111827",
    "resultsBackground": "#ffffff",
    "resultHoverBackground": "#f3f4f6",
    "highlightColor": "#3b82f6",
    "fontSize": "0.875rem",
    "borderRadius": "0.375rem"
  }
}

Style Properties

Search Index Configuration

Advanced configuration for what gets indexed.

Edit config/site.json:

{
  "search": {
    "indexing": {
      "excludePages": [],
      "excludeSelectors": [],
      "includeCodeBlocks": false
    }
  }
}

Exclude Specific Pages

Exclude pages from search index:

{
  "search": {
    "indexing": {
      "excludePages": [
        "/changelog",
        "/legal/privacy-policy"
      ]
    }
  }
}

Exclude Content Selectors

Exclude specific HTML elements from indexing:

{
  "search": {
    "indexing": {
      "excludeSelectors": [
        ".no-search",
        "#exclude-this",
        ".draft-content"
      ]
    }
  }
}

Then in your markdown, use HTML:

<div class="no-search">
This content won't be searchable.
</div>

Include Code Blocks

By default, code blocks are excluded from search. To include them:

{
  "search": {
    "indexing": {
      "includeCodeBlocks": true
    }
  }
}

Per-Page Search Control

Exclude individual pages from search using frontmatter:

---
title: Draft Page
search: false
---

# Draft Page

This page won't appear in search results.

Useful for:

• Draft content
• Private documentation
• Legacy pages
• Archived content

Search Best Practices

Write Searchable Content

Good practices:

• Use descriptive headings
• Include keywords naturally
• Write clear page titles
• Use consistent terminology
• Add meaningful alt text to images

Example:

# Authentication Guide

Learn how to authenticate users with API keys and OAuth.

## API Key Authentication

Generate and use API keys for server-to-server authentication.

## OAuth Flow

Implement OAuth 2.0 for user authentication in web applications.

This content is highly searchable with clear terms and structure.

Optimize Titles and Headings

Titles and headings have higher search weight:

---
title: Getting Started with Mordoc
description: Quick start guide for creating documentation with Mordoc
---

# Getting Started with Mordoc

## Install Prerequisites
## Create Your First Project
## Deploy Your Documentation

Users searching "getting started" or "create project" will find this easily.

Use Synonyms

Include common alternative terms:

# Configuration (Settings)

Configure (customize, set up) your Mordoc documentation site.

This helps users find content regardless of terminology.

Search Performance

Index Size

The search index size depends on:

• Number of pages
• Content length
• Included/excluded content

Typical sizes:

• Small site (10 pages): ~50 KB
• Medium site (100 pages): ~300 KB
• Large site (1000 pages): ~2-3 MB

Optimize Index Size

1. Exclude unnecessary pages: Legal, changelog, archives
2. Don't index code blocks: Unless specifically needed
3. Use shorter excerpts: Reduce excerptLength
4. Exclude boilerplate: Use excludeSelectors

Multi-Language Search

For multilingual documentation, search automatically:

• Searches only the current language
• Maintains separate indexes per language
• Respects language-specific rules

Configure per language in config/site.json:

{
  "languages": {
    "en": {
      "search": {
        "placeholder": "Search..."
      }
    },
    "es": {
      "search": {
        "placeholder": "Buscar..."
      }
    }
  }
}

Accessibility

Search is built with accessibility:

• Keyboard Navigation: Full keyboard support
• Screen Reader: ARIA labels and announcements
• Focus Management: Clear focus indicators
• Semantic HTML: Proper landmarks and roles

Troubleshooting

Search Not Working

• Verify enabled: true in configuration
• Check site was built: npm run build
• Ensure JavaScript is enabled in browser
• Clear browser cache
• Check browser console for errors

No Results Found

• Verify content exists in markdown files
• Check page isn't excluded from search
• Ensure proper build completed
• Try rebuilding search index

Slow Search Performance

• Reduce maxResults count
• Exclude unnecessary pages
• Don't index code blocks
• Reduce excerpt length
• Check index file size

Search Index Not Updating

• Run full rebuild: npm run build
• Clear dist/ directory before building
• Check for build errors
• Verify all content files are saved

Advanced Features

Custom Search Filters

Add metadata for filtering:

---
title: API Guide
category: api
version: 2.0
---

Configure filters:

{
  "search": {
    "filters": {
      "category": ["api", "guides", "tutorials"],
      "version": ["1.0", "2.0"]
    }
  }
}

Search Analytics

Track search queries (requires integration):

{
  "search": {
    "analytics": {
      "enabled": true,
      "provider": "google-analytics",
      "trackingId": "GA-XXXXXXX"
    }
  }
}

Examples

Basic Configuration

{
  "search": {
    "enabled": true,
    "placeholder": "Search docs...",
    "maxResults": 10
  }
}

Exclude Pages Configuration

{
  "search": {
    "enabled": true,
    "indexing": {
      "excludePages": [
        "/changelog",
        "/legal/*",
        "/drafts/*"
      ]
    }
  }
}

Custom Styled Search

{
  "search": {
    "placeholder": "What can we help you find?",
    "inputBackground": "#f9fafb",
    "highlightColor": "#059669",
    "maxResults": 15,
    "fontSize": "1rem"
  }
}

Next Steps

• Branding - Customize logo and appearance
• Build - Build your site with search enabled
• Preview - Test search locally before deploying