Fuzzy search results

StaticSearch now finds partial segments of words so there’s less need to type them in full.

• When you type the characters "exp", the results show pages containing words such as “expert”, “explain”, “explicit”, “explore”, “export”, and “express”.

• Changing the search term to "expl" returns pages with the words “explain”, “explicit”, and “explore”.

• Changing it to "expla" then returns pages with “explain”.

A fuzzy setting determines the maximum number of words to fetch. Set it on the web component:

HTML excerpt

<static-search fuzzy="5">
<p>search</p>
</static-search>

the bind module <input> field:

HTML excerpt

<input type="search" id="staticsearch_search" fuzzy="5">

or as the second argument of the API .find() method:

JavaScript excerpt

const result = await staticsearch.find('my search query', 5);

• The default fuzzy value is 6. Searching for "exp" returns results for all six words above.
• Setting fuzzy="3" returns results for the first three words (“expert”, “explain”, and “explicit”).
• Setting fuzzy="1" or lower reverts to the original search behaviour and the user must type most of the word before results appear.

Keyboard-focusable activation

The <static-search> activation element which triggers the search dialog is now keyboard-focusable so you can open it by hitting Enter or space.

Activate search from any element

When using the <static-search> web component, any HTML element can trigger the search dialog by adding a data-static-search attribute, e.g.

HTML excerpt

<a href="#" data-static-search="search">click here to search</a>

Activation element ::part name

The activation element sets a part attribute name of activate unless you define your own, e.g.

HTML excerpt

<static-search fuzzy="5">
<p part="trigger">search</p>
</static-search>

Style it using the part name, e.g.

CSS excerpt

static-search::part(trigger) {
color: #00f;
}

Build directory location

The StaticSearch indexer now looks for static sites built to the subdirectories:

1. ./build/
2. ./dist/
3. ./dest/
4. ./out/, or
5. ./target/

When none exist, it uses the current working directory.

Omit default stop words

StaticSearch automatically removes common stop words considered insignificant to the meaning of text – such as “and”, “the”, and “but” in English. It supports stop words in Afrikaans (af), Croatian (hr), Czech (cs), Danish (da), Dutch (nl), English (en), Estonian (et), Finnish (fi), French (fr), German (de), Hungarian (hu), Irish (ga), Italian (it), Latvian (lv), Lithuanian (lt), Malay (ms), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Slovak (sk), Somali (so), Spanish (es), Swahili (sw), Swedish (sv), Turkish (tr), and Zulu (zu).

In some cases, such as smaller sites, you may wish to omit these defaults or use your own set. You can do this on the command line:

terminal

staticsearch -W
# or
staticsearch --ignorestopdefault

in an environment variable:

example .env

# StaticSearch environment variables
STOPWORDS_DEFAULT=false

or using the Node.js API:

index.js example

// run indexer
import { staticsearch } from 'staticsearch';
staticsearch.stopWordsDefault = false;
await staticsearch.index();

Miscellaneous updates

Minor changes include:

• Index files are generated to a search subdirectory of the build directory unless overridden.
• The search result scrollbar thumbs now use the --staticsearch-color-fore2 color.
• Words with valid technical meanings have been removed from the English stop word list.
• Slug paths generated on Windows devices now use / rather than \.

Get started

The StaticSearch documentation provides a quick start guide, and details about the indexer, web component, bind module, and JavaScript API.

StaticSearch works well with Publican sites. The Publican documentation provides a quick start guide, a detailed set-up guide, API references, and common recipes you can use and adapt for your own projects.

• Get started
• Donate

This was a third-party module update so there are no breaking changes.

Documentation theme

A new Publican theme is available that’s designed for documentation websites.

• demonstration site:

  https://publican-theme-doc.pages.dev/

• code repository:

  github.com/craigbuckler/publican.theme.doc

The theme is fast, standards based, and uses best practise techniques. It features main menus, page menus, StaticSearch, a responsive layout, a light/dark switcher, sitemaps, security, and a 100% Lighthouse performance score.

The theme uses new CSS techniques to provide complimentary light and dark mode color schemes from a single hue value (0 to 360) set in the .env.dev file:

.env.dev

# default blue
SITE_THEMEHUE=270

If necessary, you can override this and specify your own CSS colors. The theme uses esbuild to bundle and minify client-side CSS and JavaScript files.

Please download and adapt the theme for your own purposes. Alternatives are available on the themes page.

Get started

The Publican documentation provides a quick start guide, a detailed set-up guide, API references, and common recipes you can use and adapt for your own projects.

• Get started
• Donate

Improved results ordering

The latest update:

1. orders results from highest to lowest relevancy as before.

2. If those values match, it orders results from highest to lowest found value (a number between 0 and 1 that indicates the proportion of search words found in a page).

3. If those values match, it orders results from newest to oldest date.

Highlight search words

Setting a highlight attribute on the web component or bind module scrolls to and highlights the first matching search terms on a results page.

This uses text fragment links which can have issues:

1. searching for “highlight” will return pages containing “highlighted” and “highlighter”, but they are not highlighted.

2. A highlighted word could appear outside your main content, such as in a menu.

Selected search text

When using the <static-search> web component, activating search now selects the current search term as well as focusing the field. This allows quicker searches for a new term.

Additional language support

StaticSearch removes commonly-used stop words considered insignificant to the meaning of text – such as “and”, “the”, and “but” in English. This can produce better results and v0.6.0 now supports stop words in:

• Afrikaans (af)
• Croatian (hr)
• Czech (cs)
• Danish (da)
• Dutch (nl)
• English (en)
• Estonian (et)
• Finnish (fi)
• French (fr)
• German (de)
• Hungarian (hu)
• Irish (ga)
• Italian (it)
• Latvian (lv)
• Lithuanian (lt)
• Malay (ms)
• Norwegian (no)
• Polish (pl)
• Portuguese (pt)
• Romanian (ro)
• Slovak (sk)
• Somali (so)
• Spanish (es)
• Swahili (sw)
• Swedish (sv)
• Turkish (tr)
• Zulu (zu)

Smaller payload

Thanks to an esbuild update, the minified JavaScript has reduced by a couple of kilobytes to less than 11Kb – despite having more code!

Get started

The StaticSearch documentation provides a quick start guide, and details about the indexer, web component, bind module, and JavaScript API.

StaticSearch works well with Publican sites. The Publican documentation provides a quick start guide, a detailed set-up guide, API references, and common recipes you can use and adapt for your own projects.

• Get started
• Donate

There should be no breaking changes but it may change how you approach organizing content and templates.

Virtual content data objects

Previous versions of Publican permitted virtual content files that could be programmatically added, e.g.

publican.config.js

const content = `
---
title: Virtual post
description: My first virtual post
author: Craig Buckler
date: 2026-01-02
---
This is a virtual post!
`;
publican.addContent(
'article/virtual-post.md',
  content
`);

The main drawback was you had to convert values to a string and place them into the front matter … only for Publican to convert them back again! This was cumbersome when reading JSON data from a Content Management System.

The .addContent() method in Publican v0.12.0 supports an optional property/value dataObject as the third parameter:

publican.addContent( <filename>, <content> [, <dataObject> ] );

For example:

publican.config.js

publican.addContent(
'article/virtual-post.md',
null,
{
title: 'My title',
description: 'My description',
content: 'This is the page content.'
date: new Date(), // now
tags: ['automatic', 'content'],
groups: 'virtual, content'
}
);

Note:

1. Unless it’s falsy, the <content> parameter takes precedence over the data object’s content property.

2. Front matter values defined in the <content> parameter take precedence over the data object’s properties.

Refer to the .addContent() method documentation.

Markdown templates

Publican reads and outputs text files so you can create templates for HTML, XML, TXT, SVG, JSON, or any other text type. To build static web pages, you typically define HTML templates that pull in content.

Publican v0.12.0 supports templates in markdown format (with an .md extension) which Publican converts to HTML.

Refer to the templates documentation. Markdown format is also supported when adding virtual templates.

Get started

The Publican documentation provides a quick start guide, a detailed set-up guide, API references, and common recipes you can use and adapt for your own projects.

• Get started
• Donate

There should be no breaking changes unless you’ve used a custom groups: value in front matter. This is now a Publican value that controls post groups.

Post groups

You can organise pages into arbitrary groups based on any factor, e.g. featured posts, years, authors, etc. You can add any post to a group by:

1. setting a groups: front matter value, e.g. groups: featured, or

2. defining a filter function in your Publican configuration file.

The following example creates a latest group with all posts dated within the past 28 days in reverse chronological order:

publican.config.js excerpt

publican.config.groupPages = {
sortBy: 'date',
sortOrder: -1,
list: {
'latest': {
filter: data => data.date >= new Date(Date.now() - 28 * 24 * 60 * 60 * 1000)
}
}
};

You can list grouped posts in any template:

${ tacs.group.get('latest').map(
p => `<p><a href="${ p.link }">${ p.title }</a></p>`
) }

You can also generate paged index pages by adding a root path and optional size, template, and index values:

publican.config.js excerpt

publican.config.groupPages = {
sortBy: 'date',
sortOrder: -1,
size: 12,
template: 'list.html',
index: 'monthly',
list: {
'latest': {
filter: data => data.date >= new Date(Date.now() - 28 * 24 * 60 * 60 * 1000),
root: 'latest'
}
}
};

If there were 30 latest posts, an index size of 12 creates:

• latest/index.html shows posts 1 to 12
• latest/1/index.html shows posts 13 to 24
• latest/2/index.html shows posts 25 to 30

For more information, refer to Publican group indexes.

Minor fixes

Version 0.11.0 fixes the following issues:

1. Watch mode works on Windows

   Previous versions would not re-render in native Windows installations (not in WSL).

2. Disable navigation menus

   Set publican.config.nav = false if you’re not using the tacs.nav object. This should make rendering a little faster.

3. No need for empty content or template directories

   Previous versions required empty directories even when using virtual files alone.

4. Improved error reporting.

Get started

The Publican documentation provides a quick start guide, a detailed set-up guide, API references, and common recipes you can use and adapt for your own projects.

• Get started
• Donate

Logical OR/AND searches

Search results now contain a new found value that gives the proportion of search words found on a page. For example, a page featuring two of the four search words entered has a found value of 0.5. You can set a new minfound attribute on the web component or bind module to limit results to pages with an equal or higher found value.

Consider a cooking website (thanks for the suggestion, Jos!) where users can search for recipes according to ingredients they have in the cupboard:

• setting minfound="0" (the default) is a logical OR.

  A recipe page appears in results when it contains ANY of the ingredients. Recipes containing all ingredients should be at the top, but there will be less useful recipes featuring a single ingredient.

• setting minfound="1" is a logical AND.

  A recipe page appears in results when it contains ALL the ingredients. That may be a little too restrictive.

• setting minfound="0.8" means a recipe page appears in results when it contains at least 80% of the ingredients.

  Again, recipes containing all ingredients should be at the top, but there could be useful results featuring four of five ingredients entered.

StaticSearch allows you build a custom recipe search where the user could click ingredients and use a slider to change the precision / fuzziness of results.

Additional language support

StaticSearch removes commonly-used stop words considered insignificant to the meaning of text – such as “and”, “the”, and “but” in English. This can produce better results and v0.5.0 now supports stop words in:

• Danish (da)
• Dutch (nl)
• English (en)
• Finnish (fi)
• French (fr)
• German (de)
• Italian (it)
• Norwegian (no)
• Portuguese (pt)
• Spanish (es)
• Swedish (sv)
• Turkish (tr)

The lists are courtesy of Stopwords ISO.

StaticSearch on Frontend Focus

The Frontend Focus newsletter, issue 703 featured StaticSearch, so many thanks to their editors.

Get started

The StaticSearch documentation provides a quick start guide, and details about the indexer, web component, bind module, and JavaScript API.

StaticSearch works well with Publican sites. The Publican documentation provides a quick start guide, a detailed set-up guide, API references, and common recipes you can use and adapt for your own projects.

• Get started
• Donate

There should be no breaking changes.

Publican string replacement issue

Publican allows you to define content string replacements. Previous releases would run the replacement twice when content was rendered inside a template. This didn’t normally cause a problem:

publican.config.js excerpt

publican.config.replace.set('Hi', 'Hello');

However, it would matter when the replacement included the search string:

publican.config.js excerpt

publican.config.replace.set('Hi', 'Hi there');

Hi becomes Hi there which then becomes Hi there there!

Version v0.10.2 fixes this so string replacement occurs once.

StaticSearch v0.4.0 updates

The following features have been added or improved:

1. Document indexing has been improved so content can be identified even when a page does not have a <main> element.

2. You can set a log verbosity level.

3. When no search directory is set (--searchdir), it defaults to a search sub-directory in the build directory (--builddir).

4. An issue was fixed where pages were not indexed because a noindex reference was found inside minified HTML even though it was outside a <meta name="robots"> tag.

5. The README now points to the comprehensive Publican.dev StaticSearch documentation.

Get started

The Publican documentation provides a quick start guide, a detailed set-up guide, API references, and common recipes you can use and adapt for your own projects.

• Get started
• Donate

There should be no breaking changes, but the following features have been improved. We’re getting closer to a version 1.0.0 release!

Fixed slug string replacement issue

In previous Publican releases, slug string replacement occurred after the file path had been converted to a slug. Consider the following example which removes two or more digits followed by an underscore:

publican.config.js excerpt

// slug replacement - removes NN_
publican.config.slugReplace.set(/\d{2,}_/g, '');

The file path path/01_index.md is converted to /path/01_index/index.html first. The slugReplace would then convert that to /path/index/index.html and we get an unnecessary index path.

In v0.10.1, slug string replacement occurs first. The file path/01_index.md is converted to /path/index.md which then becomes /path/index.html.

The update is unlikely to break your site, but you may need to check paths are what you expect them to be.

Word count accuracy improvement

Word counts on documents with embedded <code> sections should be more accurate.

New Publican.dev tools documentation

There’s a new Tools menu on this site that provides documentation for my other utilities that can help Publican site development.

1. StaticSearch – my client-side search engine for static sites

2. LiveLocalhost – my tiny local development web server with automatic hot reloading

Get started

The Publican documentation provides a quick start guide, a detailed set-up guide, API references, and common recipes you can use and adapt for your own projects.

• Get started
• Donate

There are no breaking changes, but the following features have been improved and a new static site search engine is available.

Better performance logging

Previous releases of Publican could conflict with other applications recording Node.js performance metrics. This has been fixed using PerfPro – a new profiler that namespaces applications so records cannot clash.

Publican and related tools such as LiveLocalhost and StaticSearch have also adopted ConCol for prettier and less cluttered console logging:

Introducing StaticSearch

This site is fairly large. While it offers reasonable navigation and tags, finding the page you want can be tricky.

Static sites cannot easily provide search facilities because there’s no back-end database. You can integrate a third-party search service such as Alogia, AddSearch, or Google’s Programmable Search Engine. These index your site and provide a search API, but have an ongoing cost.

JavaScript-only search facilities such as Lunr require you to pass all content in a specific format. Every page then has a full index of your site, so the payload can become large as your site grows.

My preferred option is pagefind. This analyses your built site and creates WASM binary indexes. Unfortunately, it can require some configuration, produces quite large files, and has problems with Content Security Policies and Safari compatibility.

So I’ve rolled my own…

StaticSearch is my new search engine for static sites. It’s enabled on Publican.dev: click the search icon in the header or press Ctrl | Cmd + K.

StaticSearch is easy to use and fully compatible with Publican, but you can use any static site generator. It:

1. quickly indexes built HTML (like pagefind)
2. is pure JavaScript without any CSP issues, and
3. has a tiny payload and no AI nonsense.

At most, the search facility requires 13Kb of JavaScript and 4Kb of CSS. You can reduce that to just 6Kb if you’re building your own UI. Word index data typically totals:

• 100Kb for a 100 page site
• 800Kb for a 1,000 page site.

Index data is incrementally loaded on demand as you search for different words. Indexes are cached in IndexedDB so results appear faster the more searches you do.

StaticSearch quickstart

Assuming your static site has been generated in a sub-directory named ./build/, run StaticSearch using:

npx staticsearch

It creates a new directory named ./build/search/ containing JavaScript code and index data.

If your site is in a different directory, such as ./dist/, use:

npx staticsearch --builddir ./dist/ --searchdir ./dist/search/

You can now add a search facility to the site using HTML code on any/all pages:

<script type="module" src="/search/staticsearch-component.js"></script>
<static-search>
<p>search</p>
</static-search>

Any HTML element can be placed inside <static-search> to activate the search when it’s clicked. You may then need to rebuild your site and re-run staticsearch to ensure everything’s up to date.

StaticSearch is new – full documentation will appear on Publican.dev shortly.

Minor redesign of Publican.dev

This site’s been updated to provide search and reduce the clutter in the header.

Get started

The Publican documentation provides a quick start guide, a detailed set-up guide, API references, and common recipes you can use and adapt for your own projects.

• Get started
• Donate

There are no breaking changes, but the following features have been added.

Directory index pages

In previous releases, directory index pages (the pages listing posts in a directory) had the data.index content property set false. Sitemaps would therefore omit pages such as: /docs/1/, /docs/2/, /docs/3/, etc.

A new publican.config.dirPages.index configuration property is now available which is set to monthly by default. Index pages will appear in sitemaps unless you explicitly set it to false.

Index page content properties

Two new content properties are available:

1. data.isDirIndex

   When a page is a directory index (listing pages in a directory), data.isDirIndex is set to the directory’s root page title. The directory name is used when that is not set.

2. data.isTagIndex

   When a page is a tag index (listing pages with a specific tag), data.isDirIndex is set to the tag name.

The following example code uses data.isTagIndex to assign more descriptive titles and descriptions to tag index pages:

publican.config.js excerpt

// set tag index titles and descriptions
publican.config.processRenderStart.add(tacs => {
  tacs.all.forEach(p => {
if (p.isTagIndex) {
const posts = `post${ p.childPageTotal === 1 ? '' : 's' }`;
      p.title = `'${ p.isTagIndex }' ${ posts }`;
      p.description = `List of ${ p.childPageTotal } ${ posts } using the tag '${ p.isTagIndex }'.`;
}
});
});

New basic theme

If you missed the v0.8.0 announcement, a new basic Publican theme is available at:

• demonstration site:

  https://publican-theme-basic.pages.dev/

• code repository:

  github.com/craigbuckler/publican.theme.basic

The theme is fast, standards based, and uses best practise techniques. It features pages, blog posts, tag indexes, a light/dark switcher, RSS feed, sitemaps, security, and a 100% Lighthouse score.

The theme uses Publican alone for rendering – there are no other dependencies. In development mode, it provides a livelocalhost server to automatically reload HTML and CSS when files change.

Please download and adapt the theme for your own purposes.

Get started

The Publican documentation provides a quick start guide, a detailed set-up guide, API references, and common recipes you can use and adapt for your own projects.

• Get started
• Donate