JP Site Search

JP Site Search Documentation

JP Site Search is a professional Joomla search extension powered by Typesense. It provides fast, typo-tolerant, multi-source search for Joomla websites, intranets, municipalities, schools, agencies, documentation-heavy websites, and enterprise Joomla installations.

The extension indexes Joomla content into Typesense and serves search results through Joomla endpoints. The browser never talks directly to Typesense. This keeps API keys, collection names, raw filters, and private search metadata away from the public frontend.

What is JP Site Search?

JP Site Search replaces basic Joomla search with a modern search experience based on Typesense. It includes a full search page, autocomplete module, suggestions, analytics, source-based indexing, diagnostics, and support for multiple searchable content sources.

Core Joomla sources currently include:

• Joomla Articles - the primary content source.
• Joomla Contacts - useful for staff directories, intranets, departments, and people search.
• Joomla Categories - optional indexing of menu-linked category landing pages.

External provider plugins can add third-party sources without adding third-party code directly into the JP Site Search core package. The first external provider add-on is the DOCman provider.

What is Typesense?

Typesense is a fast open-source search engine designed for instant, typo-tolerant search. JP Site Search uses Typesense as the search backend and Joomla as the secure frontend and administration layer.

In a JP Site Search setup, Joomla is responsible for:

• Reading Joomla content and supported source data.
• Respecting Joomla access levels, publishing state, language rules, and source settings.
• Indexing safe normalized documents into Typesense.
• Receiving frontend search requests.
• Sending safe server-side search requests to Typesense.
• Returning normalized public result data to the browser.

Typesense is responsible for:

• Fast full-text search.
• Typo tolerance.
• Ranking and relevance.
• Facets and filters.
• Autocomplete and suggestion queries.

The browser should never connect directly to Typesense in a JP Site Search installation. Public visitors should only communicate with Joomla endpoints.

Typesense Hosting Options

You can run Typesense in several ways. The best option depends on your traffic, hosting skills, budget, and uptime requirements.

Typesense Cloud

Typesense Cloud is the managed hosted option from the Typesense team. This is usually the easiest way to get started because you do not need to maintain the Typesense server yourself.

Recommended for:

• Production websites where you want managed search infrastructure.
• Agencies that do not want to maintain another server service.
• Customers who prefer predictable managed hosting.
• Projects that may need high availability or global search delivery.

Useful links:

• Typesense Cloud
• Typesense installation guide

Self-hosted Typesense

You can also run Typesense yourself on a VPS, dedicated server, Docker host, or internal infrastructure.

Recommended for:

• Developers who want local control.
• Intranets or private environments.
• Customers who already operate Docker or Linux services.
• Projects where data must stay on specific infrastructure.

Useful links:

• Install Typesense
• Official Typesense Docker image
• Typesense system requirements

Recommended Typesense Server Setup

Typesense stores the search index in memory and keeps raw document data on disk. This means RAM, SSD storage, and stable CPU capacity are the most important server resources.

Small websites and development

• CPU: 1-2 vCPU
• RAM: 1-2 GB
• Disk: SSD storage
• Use case: development, small Joomla websites, proof of concept, low traffic

Normal production Joomla website

• CPU: 2-4 vCPU
• RAM: 2-4 GB or more depending on indexed content size
• Disk: SSD storage with room for raw document data and growth
• Use case: normal municipal website, company website, documentation website, intranet

Larger website or intranet

• CPU: 4+ vCPU
• RAM: sized according to indexed searchable data
• Disk: fast SSD/NVMe where possible
• Use case: large intranet, many articles/documents, many concurrent users, frequent indexing

For production systems where search uptime is critical, consider Typesense Cloud or a highly available Typesense cluster. A single self-hosted node is simpler, but it is also a single point of failure.

Always test with your real content size. Search performance depends on how many documents you index, how much text is searchable, how many fields are faceted, and how many users search at the same time.

Quick Docker Example

The following is a simple example for local testing or a small self-hosted setup. Adjust the API key, data path, port exposure, backups, and server security before using this in production.

services:
  typesense:
    image: typesense/typesense:latest
    restart: unless-stopped
    ports:
      - "8108:8108"
    volumes:
      - ./typesense-data:/data
    command:
      - "--data-dir=/data"
      - "--api-key=change-this-api-key"
      - "--enable-cors"

After starting Typesense, configure JP Site Search with:

• Host: your Typesense hostname or IP address
• Port: 8108, unless changed
• Protocol: http or https depending on setup
• API key: your server-side Typesense API key

For production use, do not expose the Typesense API publicly unless you understand the security implications. JP Site Search is designed so that frontend visitors search through Joomla, not directly through Typesense.

Installation

• Download the latest JP Site Search package.
• Install it through Joomla Extension Manager.
• Go to System -> Extensions.
• Upload and install the JP Site Search package ZIP.
• After installation, go to Components -> JP Site Search.

The main package includes the JP Site Search component, module, and system plugin. External provider add-ons, such as the DOCman provider, are installed separately.

Initial Setup

After installation, configure the Typesense connection first.

1. Go to Components -> JP Site Search -> Settings.
2. Open the Typesense tab.
3. Enter the Typesense host, port, protocol, and API key.
4. Save the settings.
5. Run the schema setup or validation tool.
6. Run the first full index.
7. Test search in the backend Search Test view.

Recommended first workflow:

1. Configure Typesense.
2. Run Schema setup / validate.
3. Run Reindex all public content.
4. Open Diagnostics and check for warnings.
5. Test search terms from existing articles.
6. Publish the frontend module or create a menu item for the full search page.

Sources and Providers

JP Site Search uses a source/provider model.

• Source means where the searchable content comes from.
• Provider means the code that reads a source and turns it into normalized search documents.
• Type means what visitors see in filters and result labels, such as Article, Contact, Category, or Document.

Core Joomla sources are included in JP Site Search itself. Third-party integrations should be installed as separate provider plugins.

Core sources

• Joomla Articles - enabled as the core content source.
• Joomla Contacts - optional people/contact source.
• Joomla Categories - optional category landing page source.

External provider plugins

• DOCman Provider - optional add-on for DOCman documents.
• Other document, event, and product providers may be added later as separate add-ons.

External providers are disabled globally by default. This keeps the core installation clean and avoids loading third-party provider logic unless you explicitly enable it.

Joomla Articles

Joomla Articles are the main built-in source. Article indexing respects Joomla publishing state, access levels, category access, language, publish up date, and publish down date.

Article documents can include:

• Title
• Alias
• Intro text
• Full text
• Category
• Tags
• Language
• Public Joomla URL

Article URLs are generated using Joomla routing. If a suitable menu item exists, Joomla can generate a cleaner SEF URL.

Joomla Contacts

The Joomla Contacts source is useful for intranets, people directories, staff directories, departments, and municipal contact search.

Contacts are disabled by default and must be enabled from the Sources settings.

Contact indexing can include:

• Name
• Position
• Category or department
• Telephone and mobile, if enabled
• Email, if enabled
• Address, if enabled
• Miscellaneous information, if enabled

Contact privacy settings are important. Only enable fields that should be searchable and visible in search results.

JP Site Search does not expose raw Joomla user data as a search source. Joomla Contacts may be linked to users, but user data is not automatically indexed as a separate people source.

Joomla Categories

The Joomla Categories source indexes Joomla com_content categories that represent real frontend landing pages.

Categories are disabled by default.

JP Site Search only indexes Joomla content categories that have a valid published frontend menu item, such as a Category Blog or Category List menu item. Categories without valid menu items are treated as internal administrator containers and are skipped intentionally.

This avoids indexing categories that do not have clean public URLs.

Category indexing includes the category entity itself:

• Category title
• Cleaned category description
• Parent category metadata where safe
• Menu-based public URL

The category provider does not crawl or index the rendered Category Blog/List page. Articles displayed inside a category blog are indexed by the Articles source, not by the Category document.

DOCman Provider Add-on

The DOCman provider is installed separately as an external JP Site Search provider plugin.

The DOCman provider indexes DOCman document metadata into JP Site Search as document results. It does not index PDF or binary file contents in the initial version.

DOCman results can include:

• Document title
• Cleaned description
• DOCman category
• File type, where safely available
• Modified date, where available
• Safe public DOCman URL

The DOCman provider requires:

• The DOCman component installed.
• The JP Site Search DOCman provider plugin installed.
• The provider plugin enabled.
• Third-party provider plugins enabled in JP Site Search settings.
• The DOCman source enabled in the DOCman provider plugin settings.

DOCman provider settings include a visitor-facing type label. For example, the technical object type can remain document, while visitors see a label such as Documents, Files, Forms, or Downloads.

Indexing

JP Site Search uses scheduled or manual indexing. When content or source settings change, run a reindex or wait for the next scheduled indexing job.

Common indexing actions:

• Reindex all public content - indexes articles and all enabled sources.
• Reindex articles only - indexes Joomla Articles.
• Reindex contacts only - indexes Joomla Contacts when enabled.
• Reindex categories only - indexes Joomla Categories when enabled.
• Reindex documents only - indexes enabled document providers, such as DOCman, when external providers are enabled.

After schema changes or extension upgrades, run schema setup/validation and then reindex.

CLI and Cron

JP Site Search supports selective source indexing from CLI and cron. This is useful for large websites where different content types should be indexed at different frequencies.

CLI examples

php cli/joomla.php jpsitesearch:index --source=all
php cli/joomla.php jpsitesearch:index --source=articles
php cli/joomla.php jpsitesearch:index --source=contacts
php cli/joomla.php jpsitesearch:index --source=categories
php cli/joomla.php jpsitesearch:index --source=documents

On DDEV, run the command through the container:

ddev exec php web/cli/joomla.php jpsitesearch:index --source=all

Cron examples

index.php?option=com_jpsitesearch&task=cron.index&token=YOUR_TOKEN&source=all
index.php?option=com_jpsitesearch&task=cron.index&token=YOUR_TOKEN&source=articles
index.php?option=com_jpsitesearch&task=cron.index&token=YOUR_TOKEN&source=contacts
index.php?option=com_jpsitesearch&task=cron.index&token=YOUR_TOKEN&source=categories
index.php?option=com_jpsitesearch&task=cron.index&token=YOUR_TOKEN&source=documents

Example schedule:

• Contacts: hourly
• Articles: nightly
• Documents: nightly or several times per day
• All public content: weekly or after major upgrades

Frontend Module

The JP Site Search module adds an autocomplete search field to module positions such as headers, navbars, mobile menus, and custom template positions.

The module supports:

• Autocomplete results
• Query suggestions
• Phrase suggestions
• Mixed, grouped, or column-based result layouts
• Dropdown width settings
• Template-independent visibility settings
• UIkit/YOOtheme, Bootstrap 5, and generic styling modes

The visibility setting can be used to show different search modules on mobile, tablet, laptop, desktop, or extra-large layouts.

Autocomplete Layouts

The autocomplete dropdown can display results in different layouts.

• Mixed list - all result types appear in one list. This is the safest default.
• Grouped list - results are grouped by visitor-facing type labels such as Articles, Contacts, Categories, or Files.
• Columns - results appear in separate columns where layout space allows.

For small websites, the mixed list is usually enough. For intranets or multi-source websites, grouped or column layouts can make results easier to scan.

Full Search Page

The full search page provides a dedicated search results page with filters and result cards.

The search page can show:

• Search query input
• Result count
• Type filter
• Category filter
• Tag filter
• Result type labels
• Structured metadata rows
• Load more results

The Type filter uses visitor-facing labels, not technical provider names. For example, a DOCman provider can display results as Files if that is the configured label.

Analytics and Search Quality

JP Site Search includes tools to improve search quality over time.

• Analytics - shows what visitors search for.
• No-result reports - shows searches that returned no results.
• Top searches - shows popular queries.
• Suggestion candidates - helps identify useful autocomplete phrases.
• Synonyms - improves matching for alternative words and terms.
• Search curation - allows important results to be pinned for selected searches.

These tools are especially useful for municipalities, intranets, documentation sites, and large content-heavy websites.

Diagnostics

The Diagnostics view helps explain why content is or is not searchable.

Diagnostics can help with:

• Typesense connection checks
• Schema status
• Source enabled/disabled state
• Indexed document counts
• Access-level issues
• Language filtering issues
• Contacts and category source status
• External provider plugin status

If expected results are missing, Diagnostics should be one of the first places to check.

Security Model

JP Site Search is designed so that frontend visitors never communicate directly with Typesense.

Correct flow:

Browser
→ Joomla endpoint
→ server-side Typesense request
→ normalized safe result response

JP Site Search should never expose the following to public visitors:

• Typesense API keys
• Raw Typesense payloads
• Raw filter expressions
• Collection names
• Access metadata
• Administrator URLs
• Private file paths
• Unsafe external URLs

Sources and provider plugins must return safe normalized documents. JP Site Search handles public search through Joomla and applies runtime gating for enabled and disabled sources.

Troubleshooting

No results are shown

• Check that Typesense is running.
• Check the Typesense host, port, protocol, and API key.
• Run schema setup or validation.
• Run a full reindex.
• Check that the relevant source is enabled.
• Check Diagnostics for access, language, or indexing warnings.

Contacts do not appear

• Enable the Joomla Contacts source.
• Check which Contact fields are allowed for indexing.
• Run contacts-only indexing or all-content indexing.
• Check that Contacts are published and public or available to the current access level.

Categories do not appear

• Enable the Joomla Categories source.
• Make sure the category has a published frontend menu item such as Category Blog or Category List.
• Check that the category and its parent category are published and accessible.
• Run categories-only indexing.

DOCman documents do not appear

• Install and enable the JP Site Search DOCman provider plugin.
• Enable third-party provider plugins in JP Site Search settings.
• Enable the DOCman source in the DOCman provider plugin.
• Run documents-only indexing.
• Check that DOCman documents and categories are published and accessible.
• Check that a safe public DOCman URL can be generated.

Old results still appear after changing source settings

JP Site Search uses scheduled/manual indexing. After changing source settings, run a rebuild/reindex or wait for the next cron/CLI indexing run so Typesense reflects the new configuration.

Wrong language results or URLs

• Check Joomla content language settings.
• Check menu item language settings.
• Reindex after language or menu changes.
• Check Diagnostics for language-related warnings.

Recommended First Setup

For most websites, start with a conservative configuration:

• Configure Typesense connection.
• Run schema setup/validate.
• Enable Joomla Articles.
• Keep Contacts, Categories, and external providers disabled until needed.
• Run all-content indexing.
• Test Search Test in the backend.
• Add the search module to a frontend position.
• Use Mixed autocomplete layout first.
• Enable analytics and review no-result searches after launch.

For intranets, consider enabling Joomla Contacts and using source-specific cron jobs so contacts can be updated more frequently than large article archives.

For document-heavy websites, install the DOCman provider add-on and test access levels carefully before launch.