# Search: A Plugin for Pelican
[](https://github.com/pelican-plugins/search/actions)
[](https://pypi.org/project/pelican-search/)
This plugin generates an index for searching content on a Pelican-powered site.
## Why would you want this?
Static sites are, well, static… and thus usually don’t have an application server component that could be used to power site search functionality. Rather than give up control (and privacy) to third-party search engine corporations, this plugin adds elegant and self-hosted site search capability to your site. Last but not least, searches are **really** fast. 🚀
Want to see just _how_ fast? Try it out for yourself. Following are some sites that use this plugin:
* [Justin Mayer](https://justinmayer.com)
* [Open Source Alternatives](https://opensourcealternatives.org)
## Installation
This plugin uses [Stork](https://stork-search.net/) to generate a search index. Follow the [Stork installation instructions](https://stork-search.net/docs/install) to install this required command-line tool and ensure it is available within `/usr/local/bin/` or another `$PATH`-accessible location of your choosing. For example, Stork can be installed on macOS (Intel) via:
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
For macOS on ARM, install via Homebrew:
brew install stork-search/stork-tap/stork
Confirm that Stork is properly installed via:
stork --help
Once Stork has been successfully installed and tested, this plugin can be installed via:
python -m pip install pelican-search
If you are using Pelican 4.5+ with namespace plugins and don’t have a `PLUGINS` setting defined in your configuration, then the Search plugin should be auto-discovered with no further action required. If, on the other hand, you _do_ have a `PLUGINS` setting defined (because you also use legacy plugins or because you want to be able to selectively disable installed plugins), then you must manually add `search` to the `PLUGINS` list, as described in the [Pelican plugins documentation][].
## Settings
This plugin’s behavior can be customized via Pelican settings. Those settings, and their default values, follow below.
### `STORK_INPUT_OPTIONS = ""`
In addition to plain-text files, Stork can recognize and index HTML and Markdown-formatted content. The default behavior of this plugin is to index generated HTML files, since Stork is good at extracting content from tags, scripts, and styles. But that mode may require a slight theme modification that isn’t necessary when indexing Markdown source (see HTML selector setting below). That said, indexing Markdown means that markup information may not be removed from the indexed content and will thus be visible in the search preview results. With that caveat aside, if you want to index Markdown source content files instead of the generated HTML output, you can set `base_directory` to your content path.
Any other setting then the output path will toggle the plugin to switch to "source" mode.
**Example**:
```python
STORK_INPUT_OPTIONS = {
base_directory = PATH
}
```
#### Stork HTML Selector
By default, Stork looks for `<main>[…]</main>` tags to determine where your main content is located. If such tags do not already exist in your theme’s template files, you can either (1) add `<main>` tags or (2) change the HTML selector that Stork should look for.
To use the default `main` selector, in each of your theme’s relevant template files, wrap the content you want to index with `<main>` tags. For example:
`article.html`:
```jinja
<main>
{{ article.content }}
</main>
```
`page.html`:
```jinja
<main>
{{ page.content }}
</main>
```
For more information, refer to [Stork’s documentation on HTML tag selection](https://stork-search.net/docs/html).
**Example**:
To set it to a different selector (for example, `primary`), you can set it like this:
```python
STORK_INPUT_OPTIONS = {
html_selector = "primary"
}
```
Additional [Input Options](https://stork-search.net/docs/config-ref) can be added here as a `dict`.
**Example**:
```python
STORK_INPUT_OPTIONS = {
url_prefix = SITEURL
}
```
### `STORK_OUTPUT_OPTIONS = ""`
[Output Options](https://stork-search.net/docs/config-ref) can be configured as a `dict`.
Keep in mind that keys are case-sensitive and must be lower case.
**Example**:
```python
STORK_OUTPUT_OPTIONS = {
debug = true
}
```
## Static Assets
There are two options for serving the necessary JavaScript, WebAssembly, and CSS static assets:
1. Use a content delivery network (CDN) to serve Stork’s static assets
2. Self-host the Stork static assets
The first option is easier to set up. The second option is provided for folks who prefer to self-host everything. After you have decided which option you prefer, follow the relevant section’s instructions below.
### Static Assets — Option 1: Use CDN
#### CSS
Add the Stork CSS before the closing `</head>` tag in your theme’s base template file, such as `base.html`:
```html
<link rel="stylesheet" href="https://files.stork-search.net/basic.css" />
```
If your theme supports dark mode, you may want to also add Stork’s dark CSS file:
```html
<link
rel="stylesheet"
media="screen and (prefers-color-scheme: dark)"
href="https://files.stork-search.net/dark.css"
/>
```
#### JavaScript
Add the following script tags to your theme’s base template, just before your closing `</body>` tag, which will load the most recent Stork module along with the matching WASM binary:
```html
<script src="https://files.stork-search.net/releases/v1.5.0/stork.js"></script>
<script>
stork.register("sitesearch", "{{ SITEURL }}/search-index.st");
</script>
```
### Static Assets — Option 2: Self-Host
Download the Stork JavaScript, WebAssembly, and CSS files and put them in your theme’s respective static asset directories:
```shell
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
Add the Stork CSS before the closing `</head>` tag in your theme’s base template file, such as `base.html`:
```jinja
<link rel="stylesheet" href="{{ SITEURL }}/{{ THEME_STATIC_DIR }}/css/stork.css">
```
If your theme supports dark mode, you may want to also add Stork’s dark CSS file:
```jinja
<link rel="stylesheet" media="screen and (prefers-color-scheme: dark)" href="{{ SITEURL }}/{{ THEME_STATIC_DIR }}/css/stork-dark.css">
```
#### JavaScript & WebAssembly
Add the following script tags to your theme’s base template file, such as `base.html`, just before the closing `</body>` tag:
```jinja
<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>
```
### Search Input Form
Decide in which place(s) on your site you want to put your search field, such as your `index.html` template file. Then add the search field to the template:
```html
Search: <input data-stork="sitesearch" />
<div data-stork="sitesearch-output"></div>
```
For more information regarding this topic, see the [Stork search interface documentation](https://stork-search.net/docs/interface).
## Deployment
Ensure your production web server serves the WebAssembly file with the `application/wasm` MIME type. For folks using older versions of Nginx, that might look like the following:
```nginx
…
http {
…
include mime.types;
# Types not included in older Nginx versions:
types {
application/wasm wasm;
}
…
}
```
For other self-hosting considerations, see the [Stork self-hosting documentation](https://stork-search.net/docs/self-hosting).
## Contributing
Contributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on [existing issues][].
To start contributing to this plugin, review the [Contributing to Pelican][] documentation, beginning with the **Contributing Code** section.
[Pelican plugins documentation]: https://docs.getpelican.com/en/latest/plugins.html
[existing issues]: https://github.com/pelican-plugins/search/issues
[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html
Raw data
{
"_id": null,
"home_page": "https://github.com/pelican-plugins/search",
"name": "pelican-search",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<4.0",
"maintainer_email": "",
"keywords": "pelican,plugin,search,index",
"author": "Justin Mayer",
"author_email": "entroP@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ac/44/5db6efe345d70a31cc79d7bd59cc10108c54550fefa1aa28f4a3c7113899/pelican_search-1.1.0.tar.gz",
"platform": null,
"description": "# Search: A Plugin for Pelican\n\n[](https://github.com/pelican-plugins/search/actions)\n[](https://pypi.org/project/pelican-search/)\n\nThis plugin generates an index for searching content on a Pelican-powered site.\n\n\n## Why would you want this?\n\nStatic sites are, well, static\u2026 and thus usually don\u2019t have an application server component that could be used to power site search functionality. Rather than give up control (and privacy) to third-party search engine corporations, this plugin adds elegant and self-hosted site search capability to your site. Last but not least, searches are **really** fast. \ud83d\ude80\n\nWant to see just _how_ fast? Try it out for yourself. Following are some sites that use this plugin:\n\n* [Justin Mayer](https://justinmayer.com)\n* [Open Source Alternatives](https://opensourcealternatives.org)\n\n\n## Installation\n\nThis plugin uses [Stork](https://stork-search.net/) to generate a search index. Follow the [Stork installation instructions](https://stork-search.net/docs/install) to install this required command-line tool and ensure it is available within `/usr/local/bin/` or another `$PATH`-accessible location of your choosing. For example, Stork can be installed on macOS (Intel) via:\n\n export STORKVERSION=\"v1.5.0\"\n wget -O /usr/local/bin/stork https://files.stork-search.net/releases/$STORKVERSION/stork-macos-10-15\n chmod +x /usr/local/bin/stork\n\nFor macOS on ARM, install via Homebrew:\n\n brew install stork-search/stork-tap/stork\n\nConfirm that Stork is properly installed via:\n\n stork --help\n\nOnce Stork has been successfully installed and tested, this plugin can be installed via:\n\n python -m pip install pelican-search\n\nIf you are using Pelican 4.5+ with namespace plugins and don\u2019t have a `PLUGINS` setting defined in your configuration, then the Search plugin should be auto-discovered with no further action required. If, on the other hand, you _do_ have a `PLUGINS` setting defined (because you also use legacy plugins or because you want to be able to selectively disable installed plugins), then you must manually add `search` to the `PLUGINS` list, as described in the [Pelican plugins documentation][].\n\n\n## Settings\n\nThis plugin\u2019s behavior can be customized via Pelican settings. Those settings, and their default values, follow below.\n\n### `STORK_INPUT_OPTIONS = \"\"`\n\nIn addition to plain-text files, Stork can recognize and index HTML and Markdown-formatted content. The default behavior of this plugin is to index generated HTML files, since Stork is good at extracting content from tags, scripts, and styles. But that mode may require a slight theme modification that isn\u2019t necessary when indexing Markdown source (see HTML selector setting below). That said, indexing Markdown means that markup information may not be removed from the indexed content and will thus be visible in the search preview results. With that caveat aside, if you want to index Markdown source content files instead of the generated HTML output, you can set `base_directory` to your content path.\n\nAny other setting then the output path will toggle the plugin to switch to \"source\" mode.\n\n**Example**:\n\n```python\nSTORK_INPUT_OPTIONS = {\n base_directory = PATH\n}\n```\n\n#### Stork HTML Selector\n\nBy default, Stork looks for `<main>[\u2026]</main>` tags to determine where your main content is located. If such tags do not already exist in your theme\u2019s template files, you can either (1) add `<main>` tags or (2) change the HTML selector that Stork should look for.\n\nTo use the default `main` selector, in each of your theme\u2019s relevant template files, wrap the content you want to index with `<main>` tags. For example:\n\n`article.html`:\n\n```jinja\n<main>\n{{ article.content }}\n</main>\n```\n\n`page.html`:\n\n```jinja\n<main>\n{{ page.content }}\n</main>\n\n```\n\nFor more information, refer to [Stork\u2019s documentation on HTML tag selection](https://stork-search.net/docs/html).\n\n**Example**:\n\nTo set it to a different selector (for example, `primary`), you can set it like this:\n\n```python\nSTORK_INPUT_OPTIONS = {\n html_selector = \"primary\"\n}\n```\n\nAdditional [Input Options](https://stork-search.net/docs/config-ref) can be added here as a `dict`.\n\n**Example**:\n\n```python\nSTORK_INPUT_OPTIONS = {\n url_prefix = SITEURL\n}\n```\n\n### `STORK_OUTPUT_OPTIONS = \"\"`\n\n[Output Options](https://stork-search.net/docs/config-ref) can be configured as a `dict`.\nKeep in mind that keys are case-sensitive and must be lower case.\n\n**Example**:\n\n```python\nSTORK_OUTPUT_OPTIONS = {\n debug = true\n}\n```\n\n## Static Assets\n\nThere are two options for serving the necessary JavaScript, WebAssembly, and CSS static assets:\n\n1. Use a content delivery network (CDN) to serve Stork\u2019s static assets\n2. Self-host the Stork static assets\n\nThe first option is easier to set up. The second option is provided for folks who prefer to self-host everything. After you have decided which option you prefer, follow the relevant section\u2019s instructions below.\n\n### Static Assets \u2014 Option 1: Use CDN\n\n#### CSS\n\nAdd the Stork CSS before the closing `</head>` tag in your theme\u2019s base template file, such as `base.html`:\n\n```html\n<link rel=\"stylesheet\" href=\"https://files.stork-search.net/basic.css\" />\n```\n\nIf your theme supports dark mode, you may want to also add Stork\u2019s dark CSS file:\n\n```html\n<link\n rel=\"stylesheet\"\n media=\"screen and (prefers-color-scheme: dark)\"\n href=\"https://files.stork-search.net/dark.css\"\n/>\n```\n\n#### JavaScript\n\nAdd the following script tags to your theme\u2019s base template, just before your closing `</body>` tag, which will load the most recent Stork module along with the matching WASM binary:\n\n```html\n<script src=\"https://files.stork-search.net/releases/v1.5.0/stork.js\"></script>\n<script>\n stork.register(\"sitesearch\", \"{{ SITEURL }}/search-index.st\");\n</script>\n```\n\n### Static Assets \u2014 Option 2: Self-Host\n\nDownload the Stork JavaScript, WebAssembly, and CSS files and put them in your theme\u2019s respective static asset directories:\n\n```shell\nexport STORKVERSION=\"v1.5.0\"\ncd $YOUR-THEME-DIR\nmkdir -p static/{js,css}\nwget -O static/js/stork.js https://files.stork-search.net/releases/$STORKVERSION/stork.js\nwget -O static/js/stork.js.map https://files.stork-search.net/releases/$STORKVERSION/stork.js.map\nwget -O static/js/stork.wasm https://files.stork-search.net/releases/$STORKVERSION/stork.wasm\nwget -O static/css/stork.css https://files.stork-search.net/basic.css\nwget -O static/css/stork-dark.css https://files.stork-search.net/dark.css\n```\n\n#### CSS\n\nAdd the Stork CSS before the closing `</head>` tag in your theme\u2019s base template file, such as `base.html`:\n\n```jinja\n<link rel=\"stylesheet\" href=\"{{ SITEURL }}/{{ THEME_STATIC_DIR }}/css/stork.css\">\n```\n\nIf your theme supports dark mode, you may want to also add Stork\u2019s dark CSS file:\n\n```jinja\n<link rel=\"stylesheet\" media=\"screen and (prefers-color-scheme: dark)\" href=\"{{ SITEURL }}/{{ THEME_STATIC_DIR }}/css/stork-dark.css\">\n```\n\n#### JavaScript & WebAssembly\n\nAdd the following script tags to your theme\u2019s base template file, such as `base.html`, just before the closing `</body>` tag:\n\n```jinja\n<script src=\"{{ SITEURL }}/{{ THEME_STATIC_DIR }}/js/stork.js\"></script>\n<script>\n stork.initialize(\"{{ SITEURL }}/{{ THEME_STATIC_DIR }}/js/stork.wasm\")\n stork.downloadIndex(\"sitesearch\", \"{{ SITEURL }}/search-index.st\")\n stork.attach(\"sitesearch\")\n</script>\n```\n\n### Search Input Form\n\nDecide in which place(s) on your site you want to put your search field, such as your `index.html` template file. Then add the search field to the template:\n\n```html\nSearch: <input data-stork=\"sitesearch\" />\n<div data-stork=\"sitesearch-output\"></div>\n```\n\nFor more information regarding this topic, see the [Stork search interface documentation](https://stork-search.net/docs/interface).\n\n\n## Deployment\n\nEnsure your production web server serves the WebAssembly file with the `application/wasm` MIME type. For folks using older versions of Nginx, that might look like the following:\n\n```nginx\n\u2026\nhttp {\n \u2026\n include mime.types;\n # Types not included in older Nginx versions:\n types {\n application/wasm wasm;\n }\n \u2026\n}\n```\n\nFor other self-hosting considerations, see the [Stork self-hosting documentation](https://stork-search.net/docs/self-hosting).\n\n\n## Contributing\n\nContributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on [existing issues][].\n\nTo start contributing to this plugin, review the [Contributing to Pelican][] documentation, beginning with the **Contributing Code** section.\n\n[Pelican plugins documentation]: https://docs.getpelican.com/en/latest/plugins.html\n[existing issues]: https://github.com/pelican-plugins/search/issues\n[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Pelican plugin that indexes content and enables static site searches",
"version": "1.1.0",
"split_keywords": [
"pelican",
"plugin",
"search",
"index"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4c60a9b369249d023a9d2c98b3ab0dffa1b6cecde619db036507e1e709d9fed1",
"md5": "0a501219280a4471b11fef373164ee36",
"sha256": "943032372c363bf670d677b2162f32f1b5307a4881efa3a7415897b0d7e6f039"
},
"downloads": -1,
"filename": "pelican_search-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0a501219280a4471b11fef373164ee36",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<4.0",
"size": 6595,
"upload_time": "2023-04-12T08:51:45",
"upload_time_iso_8601": "2023-04-12T08:51:45.600584Z",
"url": "https://files.pythonhosted.org/packages/4c/60/a9b369249d023a9d2c98b3ab0dffa1b6cecde619db036507e1e709d9fed1/pelican_search-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ac445db6efe345d70a31cc79d7bd59cc10108c54550fefa1aa28f4a3c7113899",
"md5": "84a9753a11e7469f38c083aec033f940",
"sha256": "9bdfb37a69404335c6b510fc4f73341c9f140e3e7320dd3868d4f045812a8d18"
},
"downloads": -1,
"filename": "pelican_search-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "84a9753a11e7469f38c083aec033f940",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<4.0",
"size": 6445,
"upload_time": "2023-04-12T08:51:58",
"upload_time_iso_8601": "2023-04-12T08:51:58.317111Z",
"url": "https://files.pythonhosted.org/packages/ac/44/5db6efe345d70a31cc79d7bd59cc10108c54550fefa1aa28f4a3c7113899/pelican_search-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-12 08:51:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "pelican-plugins",
"github_project": "search",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pelican-search"
}
JSON
