feat: make pagefind the new default search engine

assets/default/pagefind.css

@@ -0,0 +1,152 @@
+#multi-page-nav .search {
+    margin-left: auto;
+    font-size: 16px;
+}
+
+#multi-page-nav .search .search-keybinding {
+    float: right;
+    width: 0;
+    transform: translateX(-1em);
+    color: #999;
+}
+
+#multi-page-nav .search:focus-within .search-keybinding {
+    display: none;
+}
+
+#multi-page-nav .search #search-input {
+    border: 1px solid #666;
+    border-radius: 3.2px;
+    color: #999;
+    background-color: unset;
+    height: 28px;
+    font-family: inherit;
+    width: 20em;
+    font-size: 14px;
+    padding: 0 8px;
+}
+
+#multi-page-nav .search #search-input::placeholder {
+    color: #999;
+    opacity: 1;
+}
+
+#multi-page-nav .search:focus-within #search-input {
+    background-color: #fff;
+    outline: none;
+    box-shadow: none;
+    color: #000;
+}
+
+.theme--documenter-dark #multi-page-nav .search:focus-within #search-input {
+    background-color: #202227;
+    color: #eee;
+}
+
+#multi-page-nav .search:focus-within .suggestions {
+    display: block;
+}
+
+#multi-page-nav .hidden {
+    display: none !important;
+}
+
+#multi-page-nav .suggestions {
+    margin: -5px 1.5rem 0 0;
+    display: none;
+    background: #fff;
+    min-width: 20em;
+    max-width: 50vw;
+    position: absolute;
+    border: 1px solid #cfd4db;
+    border-radius: 6px;
+    padding: .4rem;
+    list-style-type: none;
+    z-index: 10;
+    right: 0;
+    max-height: max(50vh, 250px);
+    overflow-y: auto;
+}
+
+.theme--documenter-dark #multi-page-nav .suggestions {
+    background: #2e3138;
+    border: 1px solid #5e6d6f;
+}
+
+#multi-page-nav .suggestions mark {
+    background-color: inherit;
+    color: #000;
+}
+.theme--documenter-dark #multi-page-nav .suggestions mark {
+    color: #fff;
+}
+
+#multi-page-nav .suggestions .suggestion {
+    line-height: 1.3;
+    border-radius: 4px;
+
+    overflow: hidden;
+    text-overflow: ellipsis;
+    word-break: break-all;
+}
+#multi-page-nav .suggestions .sub-suggestions .suggestion {
+    margin-left: 1rem;
+}
+
+#multi-page-nav .suggestions .suggestion-header {
+    padding: .4rem .6rem;
+}
+#multi-page-nav .suggestions .suggestion-header:focus-visible {
+    outline: none;
+}
+.theme--documenter-dark #multi-page-nav .suggestions .suggestion-header:hover,
+.theme--documenter-dark #multi-page-nav .suggestions .suggestion-header:focus {
+    background-color: #202227;
+}
+#multi-page-nav .suggestions .suggestion-header:hover,
+#multi-page-nav .suggestions .suggestion-header:focus {
+    background-color: #eee;
+}
+
+#multi-page-nav .suggestions .suggestion .suggestion-excerpt {
+    font-size: small;
+    color: #666;
+}
+.theme--documenter-dark #multi-page-nav .suggestions .suggestion .suggestion-excerpt {
+    color: #aaa;
+}
+
+#multi-page-nav .suggestion .suggestion-title {
+    font-size: 1.2rem;
+    font-weight: bold;
+}
+
+#multi-page-nav .suggestion .sub-suggestions .suggestion-title {
+    font-size: 1rem;
+}
+
+#multi-page-nav .suggestion a {
+    display: block;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    color: black;
+}
+
+.theme--documenter-dark #multi-page-nav .suggestion a {
+    color: white;
+}
+
+#multi-page-nav .suggestions .suggestion .page-title {
+    font-weight: bold;
+}
+
+@media screen and (max-width: 1055px) {
+    #multi-page-nav .search #search-input {
+        width: 100%;
+    }
+    #multi-page-nav .suggestions {
+        max-width: 100vw;
+        width: calc(100% - 3.5rem);
+        margin: 10px 2.5em 4.5em 0;
+    }
+}

assets/default/pagefind_integration.js

@@ -0,0 +1,150 @@
+// custom search widget
+(async function() {
+    const MAX_RESULTS = 20
+    let FOCUSABLE_ELEMENTS = []
+    let FOCUSED_ELEMENT_INDEX = 0
+
+    const pagefind = await import("/pagefind/pagefind.js");
+
+    function initialize() {
+        pagefind.init()
+        registerSearchListener()
+
+        document.body.addEventListener('keydown', ev => {
+            if (document.activeElement === document.body && (ev.key === '/' || ev.key === 's')) {
+                document.getElementById('search-input').focus()
+                ev.preventDefault()
+            }
+        })
+    }
+
+    function registerSearchListener() {
+        const input = document.getElementById('search-input')
+        const suggestions = document.getElementById('search-result-container')
+
+        async function runSearch() {
+            const query = input.value
+
+            const search = await pagefind.debouncedSearch(query, {}, 300);
+
+            if (search) {
+                buildResults(search.results)
+            }
+        }
+
+        input.addEventListener('keyup', ev => {
+            runSearch()
+        })
+
+        input.addEventListener('keydown', ev => {
+            if (ev.key === 'ArrowDown') {
+                FOCUSED_ELEMENT_INDEX = 0
+                FOCUSABLE_ELEMENTS[FOCUSED_ELEMENT_INDEX].focus()
+                ev.preventDefault()
+                return
+            } else if (ev.key === 'ArrowUp') {
+                FOCUSED_ELEMENT_INDEX = FOCUSABLE_ELEMENTS.length - 1
+                FOCUSABLE_ELEMENTS[FOCUSED_ELEMENT_INDEX].focus()
+                ev.preventDefault()
+                return
+            }
+        })
+
+        suggestions.addEventListener('keydown', ev => {
+            if (ev.key === 'ArrowDown') {
+                FOCUSED_ELEMENT_INDEX += 1
+                if (FOCUSED_ELEMENT_INDEX < FOCUSABLE_ELEMENTS.length) {
+                    FOCUSABLE_ELEMENTS[FOCUSED_ELEMENT_INDEX].focus()
+                } else {
+                    FOCUSED_ELEMENT_INDEX = -1
+                    input.focus()
+                }
+                ev.preventDefault()
+            } else if (ev.key === 'ArrowUp') {
+                FOCUSED_ELEMENT_INDEX -= 1
+                if (FOCUSED_ELEMENT_INDEX >= 0) {
+                    FOCUSABLE_ELEMENTS[FOCUSED_ELEMENT_INDEX].focus()
+                } else {
+                    FOCUSED_ELEMENT_INDEX = -1
+                    input.focus()
+                }
+                ev.preventDefault()
+            }
+        })
+
+        input.addEventListener('focus', ev => {
+            runSearch()
+        })
+    }
+
+    function renderResult(result) {
+        const entry = document.createElement('li')
+        entry.classList.add('suggestion')
+
+        const linkContainer = document.createElement('a')
+        linkContainer.classList.add('suggestion-header')
+        linkContainer.setAttribute('href', result.url)
+
+        const page = document.createElement('p')
+        page.classList.add('suggestion-title')
+
+        const pageTitle = document.createElement('span')
+        pageTitle.innerText = result.title ?? result.meta.title
+
+        page.appendChild(pageTitle)
+
+        const excerpt = document.createElement('p')
+        excerpt.classList.add('suggestion-excerpt')
+        excerpt.innerHTML = result.excerpt
+
+        linkContainer.appendChild(page)
+        linkContainer.appendChild(excerpt)
+
+        entry.appendChild(linkContainer)
+
+        return entry
+    }
+
+    async function buildResults(results) {
+        const suggestions = document.getElementById('search-result-container')
+
+        const children = await Promise.all(results.slice(0, MAX_RESULTS - 1).map(async (r, i) => {
+            const data = await r.data()
+
+            const entry = renderResult(data)
+
+            if (data.sub_results.length > 0) {
+                const subResults = document.createElement('ol')
+                subResults.classList.add('sub-suggestions')
+
+                data.sub_results.forEach(subresult => {
+                    const entry = renderResult(subresult)
+                    subResults.appendChild(entry)
+                })
+                entry.appendChild(subResults)
+            }
+
+            return entry
+        }))
+
+        if (results.length > 0) {
+            suggestions.classList.remove('hidden')
+        } else {
+            suggestions.classList.add('hidden')
+        }
+
+
+        suggestions.replaceChildren(
+            ...children
+        )
+
+        FOCUSED_ELEMENT_INDEX = -1
+        FOCUSABLE_ELEMENTS = [...suggestions.querySelectorAll('a')]
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', initialize)
+    } else {
+        initialize()
+    };
+})()

src/MultiDocumenter.jl

@@ -11,17 +11,17 @@ include("documentertools/canonical_urls.jl")
 end
 
 """
-    SearchConfig(index_versions = ["stable"], engine = MultiDocumenter.FlexSearch, lowfi = false)
+    SearchConfig(index_versions = ["stable"], engine = MultiDocumenter.PageFind, lowfi = false)
 
 `index_versions` is a vector of relative paths used for generating the search index. Only
 the first matching path is considered.
-`engine` may be `MultiDocumenter.FlexSearch`, `MultiDocumenter.Stork`, or a module that conforms
-to the expected API (which is currently undocumented).
+`engine` may be `MultiDocumenter.PageFind`, `MultiDocumenter.FlexSearch`, `MultiDocumenter.Stork`, 
+or a module that conforms to the expected API (which is currently undocumented).
 `lowfi = true` will try to minimize search index size. Only relevant for flexsearch.
 """
 Base.@kwdef mutable struct SearchConfig
     index_versions = ["stable", "dev"]
-    engine = FlexSearch
+    engine = PageFind
     lowfi = false
 end
 
@@ -131,12 +131,13 @@ function walk_outputs(f, root, docs::Vector, dirs::Vector{String})
 end
 
 include("renderers.jl")
+include("search/pagefind.jl")
 include("search/flexsearch.jl")
 include("search/stork.jl")
 include("canonical.jl")
 include("sitemap.jl")
 
-const DEFAULT_ENGINE = SearchConfig(index_versions = ["stable", "dev"], engine = FlexSearch)
+const DEFAULT_ENGINE = SearchConfig(index_versions = ["stable", "dev"], engine = PageFind)
 
 """
     make(
@@ -246,13 +247,6 @@ function make(
     isdir(out_assets) || mkpath(out_assets)
     cp(joinpath(@__DIR__, "..", "assets", "default"), joinpath(out_assets, "default"))
 
-    if search_engine != false
-        if search_engine.engine == Stork && !Stork.has_stork()
-            @warn "stork binary not found. Falling back to flexsearch as search_engine."
-            search_engine = DEFAULT_ENGINE
-        end
-    end
-
     inject_styles_and_global_navigation(
         dir,
         docs,

src/search/pagefind.jl

@@ -0,0 +1,35 @@
+module PageFind
+using NodeJS: NodeJS
+using HypertextLiteral
+
+function inject_script!(custom_scripts, rootpath)
+    pushfirst!(custom_scripts, joinpath("assets", "default", "pagefind_integration.js"))
+    pushfirst!(custom_scripts, joinpath("pagefind", "pagefind.js"))
+end
+
+function inject_styles!(custom_styles)
+    pushfirst!(custom_styles, joinpath("assets", "default", "pagefind.css"))
+end
+
+function render()
+    return @htl """
+    <div class="search nav-item">
+        <input id="search-input" placeholder="Search everywhere...">
+        <ol id="search-result-container" class="suggestions hidden">
+        </ol>
+        <div class="search-keybinding">/</div>
+    </div>
+    """
+end
+
+function build_search_index(root, docs, config, rootpath)
+    if !success(`npx pagefind -V`)
+        error("pagefind search engine not found. Aborting. Try running `npm install pagefind --global`")
+    end
+
+    pattern = "*/{$(join(config.index_versions, ","))}/**/*.{html}"
+
+    run(`npx pagefind --site $(root) --glob $(pattern) --root-selector article --exclude-selectors pre`)
+end
+
+end