PHPackages                             johannschopplich/kirby-algolia-docsearch - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Search & Filtering](/categories/search)
4. /
5. johannschopplich/kirby-algolia-docsearch

ActiveKirby-plugin[Search & Filtering](/categories/search)

johannschopplich/kirby-algolia-docsearch
========================================

Algolia DocSearch plugin for Kirby CMS

1.0.1(7mo ago)252.2k↓89.9%1[1 issues](https://github.com/johannschopplich/kirby-algolia-docsearch/issues)MITPHP

Since Jan 28Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/johannschopplich/kirby-algolia-docsearch)[ Packagist](https://packagist.org/packages/johannschopplich/kirby-algolia-docsearch)[ Docs](https://github.com/johannschopplich/kirby-algolia-docsearch#readme)[ Fund](https://paypal.me/jschopplich)[ RSS](/packages/johannschopplich-kirby-algolia-docsearch/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (3)Versions (27)Used By (0)

[![Kirby Algolia DocSearch](./.github/kirby-algolia-docsearch.png)](./.github/kirby-algolia-docsearch.png)

Kirby Algolia DocSearch
=======================

[](#kirby-algolia-docsearch)

Quickest way to integrate a search bar in your Kirby project. Index your content with a Kirby CLI command or Panel button push it to Algolia. The [Algolia's DocSearch](https://docsearch.algolia.com) JavaScript library will display a search button and result modal for you.

You can use the **Algolia free plan**, since the plugin itself indexes and parses the site. The Algolia crawler (a paid feature) is not needed. Leaving you with the option to stick with the free tier. 💸

> “But DocSearch is for documentations! My Kirby project is not a documentation!” you might add.

Well, we co-opt the DocSearch library for our own purposes. 😏 The library can be used anywhere, if the data model matches the requirements. Which it does. 🎉

Key Features
------------

[](#key-features)

- 🫡 No Algolia configuration required, just an account
- 🌐 Multi-language support
- 🆑 [Kirby CLI](https://github.com/getkirby/cli) command support
- 🧋 [Janitor](https://github.com/bnomei/kirby3-janitor) support

Requirements
------------

[](#requirements)

- Kirby 3.9+

Kirby is not free software. However, you can try Kirby and the Starterkit on your local machine or on a test server as long as you need to make sure it is the right tool for your next project. … and when you’re convinced, [buy your license](https://getkirby.com/buy).

Installation
------------

[](#installation)

### Composer

[](#composer)

```
composer require johannschopplich/kirby-algolia-docsearch
```

### Download

[](#download)

Download and copy this repository to `/site/plugins/kirby-algolia-docsearch`.

Setup
-----

[](#setup)

### Algolia Account

[](#algolia-account)

If you do not yet have an Algolia account, you [can create one](https://www.algolia.com/users/sign_up).

### DocSearch Library

[](#docsearch-library)

The DocSearch library to display the search input field and result modal is not included in this package. Follow the instructions on the [Algolia DocSearch installation website](https://docsearch.algolia.com/docs/DocSearch-v3#installation) to add it to your project.

👉 **tl;dr** Installation1. Import the required JS and CSS files in your project. Either by using a CDN or by installing the library via NPM.

    ```
    npm install @docsearch/js@3 @docsearch/css@3
    ```

    Or:

    ```

    ```
2. Create a [container](https://docsearch.algolia.com/docs/api#container) for your DocSearch component to go in.

    ```

    ```
3. Initialize the DocSearch library with your Algolia credentials.

    ```
    docsearch({
      container: "#docsearch",
      appId: "YOUR_APP_ID",
      indexName: "YOUR_INDEX_NAME",
      apiKey: "YOUR_SEARCH_API_KEY",
    });
    ```

Usage
-----

[](#usage)

### Configuration

[](#configuration)

```
# /site/config/config.php
return [
    'johannschopplich.algolia-docsearch' => [
        // Algolia App ID for the project
        'appId' => 'ALGOLIA_APP_ID',
        // Algolia API Key for the project
        'apiKey' => 'ALGOLIA_API_KEY',
        // Algolia index base name; in mutlilang projects,
        // the language code will be appended by the plugin,
        // e.g. `example-de` for German
        'index' => 'example',
        // HTML tag name which contains a page's content or
        // closure which returns the content of a page
        // If not given defaults to `body`
        'content' => 'main',
        // Register hooks to index a page on changed slug,
        // title, content or status
        'hooks' => false,
        // Templates which should be indexed
        'templates' => [
            'article',
            'default',
            'home',
            'project'
        ],
        // Optional pages which should be excluded from the index
        'exclude' => [
            'pages' => [
                'blog/some-post',
            ]
        ],
        // Define the search hit label
        'label' => [
            // Accepts a string or an array of strings for each language
            // Single language:
            // 'default' => 'Page'
            // Multiple languages:
            'default' => [
                'de' => 'Seite',
                'en' => 'Page'
            ],
            'templates' => [
                // Accepts a string or an array of strings for each language
                // Single language:
                // 'article' => 'Article'
                // Multiple languages:
                'article' => [
                    'de' => 'Artikel',
                    'en' => 'Article'
                ],
                'project' => [
                    'de' => 'Projekt',
                    'en' => 'Project'
                ]
            ]
        ],
        // Optional: Extend or override Algolia index settings
        // These settings are merged with the default DocSearch settings
        'indexSettings' => []
    ]
];
```

#### Callback for Content

[](#callback-for-content)

Instead of extracting content by an HTML tag name, you can define a closure which returns the content of a page:

```
# /site/config/config.php
return [
    'johannschopplich.algolia-docsearch' => [
        // Return any string which should be indexed
        'content' => fn (\Kirby\Cms\Page $page, string|null $languageCode) => strip_tags($page->text()->toBlocks()->toHtml())
        // other options …
    ]
];
```

In multi-language projects, you can also pass the language code to the closure and return the content for the given language:

```
# /site/config/config.php
return [
    'johannschopplich.algolia-docsearch' => [
        // Return any string which should be indexed
        'content' => function (\Kirby\Cms\Page $page, string|null $languageCode) {
            return strip_tags($page->content($languageCode)->text()->toBlocks()->toHtml());
        }
        // other options …
    ]
];
```

Defining callbacks for each template is also possible:

```
# /site/config/config.php
return [
    'johannschopplich.algolia-docsearch' => [
        // Return any string which should be indexed
        'content' => [
            'default' => fn (\Kirby\Cms\Page $page, string|null $languageCode) => strip_tags($page->text()->toBlocks()->toHtml())
            'home' => fn (\Kirby\Cms\Page $page, string|null $languageCode) => $page->description()->value()
        ]
        // other options …
    ]
];
```

### Indexing the Site

[](#indexing-the-site)

#### Kirby CLI

[](#kirby-cli)

Run the `algolia-docsearch:index` command to index your content.

```
kirby algolia-docsearch:index
```

#### Panel Button

[](#panel-button)

[![Preview of the Panel button](./.github/panel-button-preview.gif)](./.github/panel-button-preview.gif)

Given you have [Janitor](https://github.com/bnomei/kirby3-janitor) plugin installed, you can add a button to the Panel to index your content.

```
algoliaIndex:
  label: johannschopplich.algolia-docsearch.index.start
  type: janitor
  command: algolia-docsearch:index
```

#### Page Hooks

[](#page-hooks)

This plugin registers page hooks to index a given page on changed slug, title, content or status. These hooks are not triggered by default, but have to be enabled in the plugin options.

```
# /site/config/config.php
return [
    'johannschopplich.algolia-docsearch' => [
        'hooks' => true
        // other options …
    ]
];
```

With hooks enabled, you can index the whole page once and the plugin will keep the index up to date.

### Multilang Projects

[](#multilang-projects)

If languages are enabled in your Kirby project, the plugin will create an Algolia index for each language. The index name will be the value of the `index` option appended by the language code, e.g. `example-de`.

Cookbook
--------

[](#cookbook)

### Index Blocks from `text` Field

[](#index-blocks-from-text-field)

If you only want to index the main content of your pages, e.g. in a blocks field, you can define a closure for the `content` option which returns the text content of a page.

```
# /site/config/config.php
return [
    'johannschopplich.algolia-docsearch' => [
        'content' => function (\Kirby\Cms\Page $page) {
            return strip_tags($page->text()->toBlocks()->toHtml());
        }
    ]
];
```

### DocSearch Initialization in Multilang Projects

[](#docsearch-initialization-in-multilang-projects)

For multilanguage projects you have to pass the translation's index name to the DocSearch library. You can extract the `lang` attribute from the `html` tag and append it to the index name.

```
const indexName = `example-${document.documentElement.lang}`;
docsearch({
  container: "#docsearch",
  appId: "YOUR_APP_ID",
  indexName,
  apiKey: "YOUR_SEARCH_API_KEY",
});
```

### Styling the Search Modal

[](#styling-the-search-modal)

The DocSearch library provides a [customization API](https://docsearch.algolia.com/docs/styling#customization-api) to style the search modal. You can add the following CSS to your project to style the search modal.

Special Thanks
--------------

[](#special-thanks)

- [Wolf-Dieter Grabner](https://photos.flowlabs.studio) for sponsoring the initial version of this package. 🙏
- Lukas Bestle and Nico Hoffmann for their [Algolia integration](https://github.com/getkirby/getkirby.com/tree/main/site/plugins/search).

License
-------

[](#license)

[MIT](./LICENSE) License © 2023-PRESENT [Johann Schopplich](https://github.com/johannschopplich)

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance62

Regular maintenance activity

Popularity28

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~41 days

Recently: every ~153 days

Total

26

Last Release

227d ago

Major Versions

0.6.1 → 1.0.02025-11-19

### Community

Maintainers

![](https://www.gravatar.com/avatar/b9be5bf8dd3a36f63c00f92a115f1109567745fb3b068617341ffc8a90755d6c?d=identicon)[johannschopplich](/maintainers/johannschopplich)

---

Top Contributors

[![johannschopplich](https://avatars.githubusercontent.com/u/27850750?v=4)](https://github.com/johannschopplich "johannschopplich (89 commits)")

---

Tags

algoliaalgolia-docsearchkirby-cmskirby-pluginkirby4kirby5searchindexkirbyalgoladocsearch

### Embed Badge

![Health badge](/badges/johannschopplich-kirby-algolia-docsearch/health.svg)

```
[![Health](https://phpackages.com/badges/johannschopplich-kirby-algolia-docsearch/health.svg)](https://phpackages.com/packages/johannschopplich-kirby-algolia-docsearch)
```

###  Alternatives

[getkirby/cms

The Kirby core

1.5k584.8k473](/packages/getkirby-cms)[algolia/scout-extended

Scout Extended extends Laravel Scout adding algolia-specific features

4196.7M6](/packages/algolia-scout-extended)[terminal42/escargot

A web crawler or spider library based on Symfony components

581.5M7](/packages/terminal42-escargot)[floriansemm/solr-bundle

Symfony Solr integration bundle

12480.5k2](/packages/floriansemm-solr-bundle)[opensearchserver/opensearchserver

PHP library for OpenSearchServer: professionnal search engine, crawlers (web, file, database), REST APIs, .... This library uses OpenSearchServer's V2 API.

4768.0k](/packages/opensearchserver-opensearchserver)[medienbaecker/kirby-modules

Easily add modules to your pages

895.5k1](/packages/medienbaecker-kirby-modules)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)