Package: pelican-search
Search: A Plugin for PelicanThis 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 arereallyfast. 🚀Want to see justhowfast? Try it out for yourself. Following are some sites that use this plugin:Justin MayerOpen Source AlternativesInstallationThis plugin usesStorkto generate a search index. Follow theStork installation instructionsto 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/storkFor macOS on ARM, install via Homebrew:brew install stork-search/stork-tap/storkConfirm that Stork is properly installed via:stork --helpOnce Stork has been successfully installed and tested, this plugin can be installed via:python -m pip install pelican-searchIf you are using Pelican 4.5+ with namespace plugins and don’t have aPLUGINSsetting defined in your configuration, then the Search plugin should be auto-discovered with no further action required. If, on the other hand, youdohave aPLUGINSsetting defined (because you also use legacy plugins or because you want to be able to selectively disable installed plugins), then you must manually addsearchto thePLUGINSlist, as described in thePelican plugins documentation.SettingsThis 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 setbase_directoryto your content path.Any other setting then the output path will toggle the plugin to switch to "source" mode.Example:STORK_INPUT_OPTIONS={base_directory=PATH}Stork HTML SelectorBy 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 defaultmainselector, in each of your theme’s relevant template files, wrap the content you want to index with<main>tags. For example:article.html:<main>{{article.content}}</main>page.html:<main>{{page.content}}</main>For more information, refer toStork’s documentation on HTML tag selection.Example:To set it to a different selector (for example,primary), you can set it like this:STORK_INPUT_OPTIONS={html_selector="primary"}AdditionalInput Optionscan be added here as adict.Example:STORK_INPUT_OPTIONS={url_prefix=SITEURL}STORK_OUTPUT_OPTIONS = ""Output Optionscan be configured as adict.
Keep in mind that keys are case-sensitive and must be lower case.Example:STORK_OUTPUT_OPTIONS={debug=true}Static AssetsThere are two options for serving the necessary JavaScript, WebAssembly, and CSS static assets:Use a content delivery network (CDN) to serve Stork’s static assetsSelf-host the Stork static assetsThe 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 CDNCSSAdd the Stork CSS before the closing</head>tag in your theme’s base template file, such asbase.html:<linkrel="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:<linkrel="stylesheet"media="screen and (prefers-color-scheme: dark)"href="https://files.stork-search.net/dark.css"/>JavaScriptAdd 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:<scriptsrc="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-HostDownload the Stork JavaScript, WebAssembly, and CSS files and put them in your theme’s respective static asset directories:exportSTORKVERSION="v1.5.0"cd$YOUR-THEME-DIR
mkdir-pstatic/{js,css}wget-Ostatic/js/stork.jshttps://files.stork-search.net/releases/$STORKVERSION/stork.js
wget-Ostatic/js/stork.js.maphttps://files.stork-search.net/releases/$STORKVERSION/stork.js.map
wget-Ostatic/js/stork.wasmhttps://files.stork-search.net/releases/$STORKVERSION/stork.wasm
wget-Ostatic/css/stork.csshttps://files.stork-search.net/basic.css
wget-Ostatic/css/stork-dark.csshttps://files.stork-search.net/dark.cssCSSAdd the Stork CSS before the closing</head>tag in your theme’s base template file, such asbase.html:<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:<link rel="stylesheet" media="screen and (prefers-color-scheme: dark)" href="{{SITEURL}}/{{THEME_STATIC_DIR}}/css/stork-dark.css">JavaScript & WebAssemblyAdd the following script tags to your theme’s base template file, such asbase.html, just before the closing</body>tag:<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 FormDecide in which place(s) on your site you want to put your search field, such as yourindex.htmltemplate file. Then add the search field to the template:Search:<inputdata-stork="sitesearch"/><divdata-stork="sitesearch-output"></div>For more information regarding this topic, see theStork search interface documentation.DeploymentEnsure your production web server serves the WebAssembly file with theapplication/wasmMIME type. For folks using older versions of Nginx, that might look like the following:…http{…includemime.types;# Types not included in older Nginx versions:types{application/wasmwasm;}…}For other self-hosting considerations, see theStork self-hosting documentation.ContributingContributions 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 onexisting issues.To start contributing to this plugin, review theContributing to Pelicandocumentation, beginning with theContributing Codesection.