搜索：Pelican插件

这个插件为使用Pelican的网站生成搜索内容的索引。

你为什么需要这个？

静态网站，嗯，就是静态的……因此通常没有应用程序服务器组件，无法用于实现网站搜索功能。与其将控制权（和隐私）交给第三方搜索引擎公司，此插件为您网站添加了优雅且自托管的网站搜索功能。最后但同样重要的是，搜索速度真的非常快。🚀

想知道有多快吗？自己试试吧。以下是一些使用此插件的网站

• Justin Mayer
• 开源替代方案

安装

此插件使用Stork生成搜索索引。按照Stork安装说明安装所需的命令行工具，并确保它在/usr/local/bin/或您选择的另一个$PATH可访问位置中可用。例如，Stork可以通过以下方式安装在macOS (Intel)上：

export STORKVERSION="v1.5.0"
wget -O /usr/local/bin/stork https://files.stork-search.net/releases/$STORKVERSION/stork-macos-10-15
chmod +x /usr/local/bin/stork

对于macOS on ARM，请通过Homebrew安装

brew install stork-search/stork-tap/stork

通过以下方式确认Stork已正确安装

stork --help

一旦Stork成功安装并测试，您就可以通过以下方式安装此插件

python -m pip install pelican-search

如果您正在使用Pelican 4.5+与命名空间插件，并且您的配置中没有定义PLUGINS设置，那么搜索插件应该会自动发现，无需进一步操作。另一方面，如果您确实在配置中定义了PLUGINS设置（因为您还使用了遗留插件，或者您希望能够选择性地禁用已安装的插件），那么您必须手动将search添加到PLUGINS列表中，具体方法请参阅Pelican插件文档。

设置

此插件的行为可以通过Pelican设置进行自定义。以下是一些设置及其默认值。

STORK_INPUT_OPTIONS = ""

除了纯文本文件外，Stork还可以识别并索引HTML和Markdown格式的文本。此插件的默认行为是索引生成的HTML文件，因为Stork擅长从标签、脚本和样式中提取内容。但此模式可能需要微调主题，这在索引Markdown源时是不必要的（请参阅下面的HTML选择器设置）。话虽如此，索引Markdown意味着可能不会从索引内容中删除标记信息，因此将在搜索预览结果中可见。不考虑这个限制，如果您想索引Markdown源内容文件而不是生成的HTML输出，可以将base_directory设置为您的内容路径。

除输出路径外的任何其他设置都会切换插件到“源”模式。

示例:

STORK_INPUT_OPTIONS = {
    base_directory = PATH
}

Stork HTML选择器

默认情况下，Stork会寻找<main>[…]</main>标签以确定您的主体内容所在位置。如果您的主题模板文件中尚不存在此类标签，您可以选择（1）添加<main>标签或（2）更改Stork应查找的HTML选择器。

要使用默认的main选择器，在每个相关的主题模板文件中，将您要索引的内容用<main>标签包裹起来。例如

article.html:

<main>
{{ article.content }}
</main>

page.html:

<main>
{{ page.content }}
</main>

有关更多信息，请参阅Stork关于HTML标签选择的文档。

示例:

要将它设置为不同的选择器（例如，primary），可以设置如下

STORK_INPUT_OPTIONS = {
    html_selector = "primary"
}

可以在此处添加其他输入选项，作为dict。

示例:

STORK_INPUT_OPTIONS = {
    url_prefix = SITEURL
}

STORK_OUTPUT_OPTIONS = ""

输出选项可以作为dict进行配置。请注意，键是区分大小写的，并且必须是小写。

示例:

STORK_OUTPUT_OPTIONS = {
    debug = true
}

静态资源

有两种方式可以提供必要的JavaScript、WebAssembly和CSS静态资源

1. 使用内容分发网络（CDN）提供Stork的静态资源
2. 自托管Stork静态资源

第一种选项更容易设置。第二种选项是为了那些喜欢自托管所有内容的用户提供的。在您决定选择哪种选项后，请按照以下相关部分的说明进行操作。

静态资源 — 选项 1：使用 CDN

CSS

将 Stork CSS 添加到您主题的基本模板文件中，例如 base.html 的 </head> 标签之前

<link rel="stylesheet" href="https://files.stork-search.net/basic.css" />

如果您的主题支持暗黑模式，您可能还需要添加 Stork 的暗黑 CSS 文件

<link
    rel="stylesheet"
    media="screen and (prefers-color-scheme: dark)"
    href="https://files.stork-search.net/dark.css"
/>

JavaScript

将以下脚本标签添加到您的主题基本模板中，在您的 </body> 标签之前，这将加载最新的 Stork 模块以及相应的 WASM 二进制文件

<script src="https://files.stork-search.net/releases/v1.5.0/stork.js"></script>
<script>
    stork.register("sitesearch", "{{ SITEURL }}/search-index.st");
</script>

静态资源 — 选项 2：自托管

下载 Stork JavaScript、WebAssembly 和 CSS 文件，并将它们放入您主题相应的静态资源目录中

export STORKVERSION="v1.5.0"
cd $YOUR-THEME-DIR
mkdir -p static/{js,css}
wget -O static/js/stork.js https://files.stork-search.net/releases/$STORKVERSION/stork.js
wget -O static/js/stork.js.map https://files.stork-search.net/releases/$STORKVERSION/stork.js.map
wget -O static/js/stork.wasm https://files.stork-search.net/releases/$STORKVERSION/stork.wasm
wget -O static/css/stork.css https://files.stork-search.net/basic.css
wget -O static/css/stork-dark.css https://files.stork-search.net/dark.css

CSS

将 Stork CSS 添加到您主题的基本模板文件中，例如 base.html 的 </head> 标签之前

<link rel="stylesheet" href="{{ SITEURL }}/{{ THEME_STATIC_DIR }}/css/stork.css">

如果您的主题支持暗黑模式，您可能还需要添加 Stork 的暗黑 CSS 文件

<link rel="stylesheet" media="screen and (prefers-color-scheme: dark)" href="{{ SITEURL }}/{{ THEME_STATIC_DIR }}/css/stork-dark.css">

JavaScript & WebAssembly

将以下脚本标签添加到您的主题基本模板文件中，例如 base.html，在您的 </body> 标签之前

<script src="{{ SITEURL }}/{{ THEME_STATIC_DIR }}/js/stork.js"></script>
<script>
    stork.initialize("{{ SITEURL }}/{{ THEME_STATIC_DIR }}/js/stork.wasm")
    stork.downloadIndex("sitesearch", "{{ SITEURL }}/search-index.st")
    stork.attach("sitesearch")
</script>

搜索输入表单

决定您想在您的网站上哪个位置放置搜索字段，例如您的 index.html 模板文件。然后将其添加到模板中

Search: <input data-stork="sitesearch" />
<div data-stork="sitesearch-output"></div>

有关此主题的更多信息，请参阅 Stork 搜索界面文档。

部署

确保您的生产 Web 服务器以 application/wasm MIME 类型提供 WebAssembly 文件。对于使用旧版本 Nginx 的用户，这看起来可能如下所示

…
http {
    …
    include             mime.types;
    # Types not included in older Nginx versions:
    types {
        application/wasm                                 wasm;
    }
    …
}

有关其他自托管考虑因素，请参阅 Stork 自托管文档。

贡献

欢迎并非常感谢贡献。每一份努力都有帮助。您可以通过改进文档、添加缺失功能以及修复错误来贡献。您还可以通过审查和评论 现有问题 来提供帮助。

要开始为此插件做出贡献，请查阅 向 Pelican 贡献 文档，从 贡献代码 部分 开始。