README

Kirby Algolia DocSearch

在您的 Kirby 项目中快速集成搜索栏的方式。使用 Kirby CLI 命令或面板按钮将内容索引到 Algolia。Algolia 的 DocSearch JavaScript 库将为您显示搜索按钮和结果模态。

由于插件本身索引和解析网站，您可以使用 Algolia 免费计划。不需要 Algolia 爬虫（付费功能）。这使您可以选择继续使用免费层。💸

“但 DocSearch 是用于文档的！我的 Kirby 项目不是文档！”你可能补充说。

嗯，我们为了自己的目的而利用了 DocSearch 库。😏只要数据模型符合要求，库可以在任何地方使用。它确实符合。🎉

主要功能

• 🫡 无需 Algolia 配置，只需账户
• 🌐 多语言支持
• 🆑 支持 Kirby CLI 命令
• 🧋 支持 Janitor

预览

要求

• Kirby 3.9+

Kirby 不是免费软件。然而，您可以在本地机器或测试服务器上尝试 Kirby 和 Starterkit，直到您确信它是您下一个项目的正确工具。…并且当您确信时，购买您的许可证。

安装

Composer

composer require johannschopplich/kirby-algolia-docsearch

下载

下载并将此存储库复制到 /site/plugins/kirby-algolia-docsearch。

设置

Algolia 账户

如果您还没有 Algolia 账户，您可以 创建一个。

DocSearch 库

显示搜索输入字段和结果模态的 DocSearch 库不包括在此包中。请按照 Algolia DocSearch 安装网站 上的说明将其添加到您的项目中。

用法

配置

# /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'
                ]
            ]
        ]
    ]
];

内容回调

您可以通过定义一个返回页面内容的闭包来提取内容，而不是通过 HTML 标签名提取内容

# /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 …
    ]
];

在多语言项目中，您还可以将语言代码传递给闭包并返回给定语言的内容

# /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 …
    ]
];

为每个模板定义回调也是可能的

# /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 …
    ]
];

索引网站

Kirby CLI

运行 algolia-docsearch:index 命令以索引您的内容。

kirby algolia-docsearch:index

面板按钮

如果您已安装 Janitor 插件，您可以向面板添加按钮以索引您的内容。

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

页面钩子

此插件用于注册页面钩子，在页面URL、标题、内容或状态变更时索引指定页面。默认情况下，这些钩子不会被触发，但需要在插件选项中启用。

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

启用钩子后，您可以一次性索引整个页面，插件将保持索引的最新状态。

多语言项目

如果您的 Kirby 项目启用了语言，插件将为每种语言创建一个 Algolia 索引。索引名称将为 index 选项的值加上语言代码，例如 example-de。

食谱

从 text 字段索引块

如果您只想索引页面的主要内容，例如在块字段中，您可以为 content 选项定义一个闭包，该闭包返回页面的文本内容。

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

多语言项目中的 DocSearch 初始化

对于多语言项目，您必须将翻译的索引名称传递给 DocSearch 库。您可以从 html 标签中提取 lang 属性并将其附加到索引名称。

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

搜索模态框的样式化

DocSearch 库提供了一个 自定义 API 来样式化搜索模态框。您可以将以下 CSS 添加到您的项目中以样式化搜索模态框。

在实际应用中，覆盖一些 CSS 自定义属性是最简单的。您可以查看 我是如何样式化组件的。

特别感谢

• Wolf-Dieter Grabner 为赞助此包的初始版本。🙏
• Lukas Bestle 和 Nico Hoffmann 为他们的 Algolia 集成。

许可协议

MIT 许可协议 © 2023-PRESENT Johann Schopplich