Lightweight Search Engine

Examples

Examples

Real-world examples of implementing Hugo SQLite Search in various scenarios. All source code is available in the GitHub repository.

Hugo Integration Examples

1. Complete Working Search Page

The repository includes a fully functional search page implementation:

To use this in your site, simply copy these files from the repository to your Hugo site.

The search page includes:

View the complete implementation in layouts/page/search.html in the repository.

2. Adding Search to Site Navigation

Update your Hugo config (hugo.yaml) to add search to the main menu:

menu:
  main:
    - identifier: search
      name: Search
      url: /search/
      weight: 50

3. Customizing the Search UI

The search page template (layouts/page/search.html) includes embedded CSS that you can customize. The default styles provide:

To customize:

  1. Edit the <style> section in layouts/page/search.html
  2. Or extract the styles to your theme’s CSS files
  3. Match your site’s existing design system

View the default CSS in the repository’s layouts/page/search.html file.

To exclude pages from the search index, add this to the page’s front matter:

---
title: "Private Page"
search: false
---

The default search data template (layouts/_default/search-data.json in the repository) already filters out:

See the template in the repository for the complete filtering logic, which you can customize.

JavaScript Client Examples

The repository includes a complete JavaScript implementation in layouts/page/search.html. Here are key patterns you can extract:

1. Basic Search Implementation

The repository shows how to:

See the HugoSearch class in layouts/page/search.html for the complete implementation.

2. Advanced Features

The reference implementation demonstrates:

Section Filtering: The loadSections() method shows how to:

Sort Options: See how to implement multiple sort orders:

Pagination: The renderPagination() method demonstrates:

All of these are implemented in layouts/page/search.html in the repository.

3. Search-as-You-Type

To implement live search:

The repository’s implementation uses a 300ms debounce to balance responsiveness with API load.

4. Result Highlighting

The API automatically provides highlighted results in these fields:

Simply use these fields in your HTML to display highlighted results. See renderResult() in the repository for an example.

5. Custom Implementations

For custom search interfaces, refer to the repository’s implementation as a starting point:

API Usage Examples

1. Testing with curl

Test the API from the command line:

# Basic search
curl "http://localhost/api/search.php?q=hugo"

# Search with filters
curl "http://localhost/api/search.php?q=search&section=docs&sort=date_desc"

# Get available sections
curl "http://localhost/api/search.php?action=sections"

# Advanced query syntax
curl "http://localhost/api/search.php?q=title:configuration+after:2024-01-01"

2. JavaScript Integration

The repository demonstrates fetch API usage patterns. Key concepts:

See the API Reference documentation for complete parameter details and response formats.

3. Advanced Query Syntax

The API supports sophisticated query syntax. Examples:

Field-specific searches:

Date filters:

Boolean operators:

Phrase search:

Complex queries:

See the API Reference for complete query syntax documentation.

Advanced Use Cases

For multi-language Hugo sites:

  1. Filter pages by language in the search data template
  2. Add a language field to the JSON output
  3. Create separate search databases per language
  4. Build each language’s index: php scripts/build-search-index.php public/en/search.db public/en/index.json

See the Configuration documentation for template customization examples.

2. Section-Specific Search Pages

To create dedicated search pages for specific sections:

  1. Create a search page with front matter specifying the section
  2. Modify the JavaScript to read the section from page metadata
  3. Automatically filter searches to that section

This is useful for documentation sites where you want separate search for docs vs. blog posts.

3. Search Analytics

Track search queries by:

This helps identify popular topics and improve content.

4. Custom Ranking

Customize relevance by modifying static/api/search.php:

The repository’s PHP code includes SQL ORDER BY clauses you can customize.

Deployment Examples

1. GitHub Actions CI/CD

The repository can be deployed automatically with GitHub Actions:

Key steps:

  1. Setup Hugo and PHP with required extensions
  2. Build Hugo site: hugo --minify
  3. Build search index: php scripts/build-search-index.php public/search.db public/index.json
  4. Deploy the public/ directory to your hosting

See the Getting Started guide for a complete GitHub Actions workflow example.

2. Traditional PHP Hosting

For shared hosting or VPS with PHP:

Deployment process:

  1. Build locally with ./build.sh
  2. Upload public/ directory via SFTP/FTP or rsync
  3. Ensure proper permissions (644 for .db, 755 for .php files)
  4. Verify PHP has SQLite3 extension enabled

Most traditional hosts (cPanel, Plesk, etc.) support this out of the box.

3. Docker Deployment

For containerized deployment:

Requirements:

The repository includes deployment script examples you can adapt.

4. Serverless Notes

Important: This solution uses PHP and SQLite, which work best with traditional or container hosting. For serverless platforms (Netlify, Vercel):

Testing

Test your search implementation:

# Basic search
curl "http://localhost/api/search.php?q=hugo" | jq '.total'

# With filters
curl "http://localhost/api/search.php?q=search&section=docs" | jq '.results[] | .title'

# Advanced queries
curl "http://localhost/api/search.php?q=title:configuration"
curl "http://localhost/api/search.php?q=after:2024-01-01"

# Get sections
curl "http://localhost/api/search.php?action=sections" | jq '.sections'

Performance Optimization

Caching strategies:

Database optimization:

Client-side:

See the Configuration documentation for specific optimization settings.

More Resources