MkDocs theme: search by title, or full text with Pagefind

tests/themes.spec.mjs

@@ -62,13 +62,22 @@ test.describe('MkDocs theme', () => {
     await page.route(/tagbrush@1/, (r) => r.fulfill({ path: 'node_modules/tagbrush/tagbrush.css', contentType: 'text/css' }));
     await page.route(/tagaction@0/, (r) => r.fulfill({ path: 'node_modules/tagaction/tagaction.js', contentType: 'text/javascript' }));
     await page.goto(pathToFileURL(resolve(`${SITE}/guide/install/index.html`)).href);
-    await expect(page.locator('body > aside nav a[aria-current="page"]')).toHaveText('Install');
+    await expect(page.locator('body > aside nav[aria-label="Documentation"] a[aria-current="page"]')).toHaveText('Install');
     await expect(page.locator('main > aside nav[aria-label="On this page"] a')).toHaveText(['Requirements', 'With pip', 'Check the install']);
     await expect(page.locator('a[rel="prev"]')).toHaveText('← Home');
     await expect(page.locator('a[rel="next"]')).toHaveText('Configure →');
     await expect(page.getByRole('button', { name: 'Copy' })).toHaveCount(2);
     await expect(page.locator('head meta[name="description"]')).toHaveAttribute('content', 'Deploy a folder of static files with one command.');
   });
+
+  test('search: a box over a list of every page and section, both hidden until TagAction shows them', async () => {
+    const { readFileSync } = await import('node:fs');
+    const html = readFileSync(`${SITE}/guide/install/index.html`, 'utf8');
+    expect(html).toMatch(/<input type="search" aria-label="Search the docs" aria-controls="tagkit-search" hidden>/);
+    expect(html).toMatch(/<ul id="tagkit-search" hidden>/);
+    const results = [...html.matchAll(/<li><a href="[^"]*">([^<]+)<\/a><\/li>/g)].map((m) => m[1]);
+    for (const title of ['Install', 'Install: With pip', 'Configure: Environment variables', 'Home: Why shipit']) expect(results).toContain(title);
+  });
 });
 
 test.describe('Hugo theme', () => {

themes/mkdocs/README.md

@@ -12,6 +12,9 @@ theme:
   name: tagkit
   primary_color: "#0f766e"   # optional brand color
   tagaction: true            # false leaves out the TagAction script
+  search: titles             # titles (default), pagefind, or false
+markdown_extensions:
+  - admonition               # !!! note callouts
 ```
 
 The page is styled by [TagBrush.css](https://github.com/kovirlabs/tagbrush) and enhanced by [TagAction](https://github.com/kovirlabs/tagaction), both loaded from a CDN.
@@ -24,10 +27,14 @@ The page is styled by [TagBrush.css](https://github.com/kovirlabs/tagbrush) and
 - Tables, footnotes, and code styled by TagBrush.css; Copy buttons on code, sortable tables, and "#" links on headings from TagAction. Everything works with JavaScript off.
 - `description` in a page's front matter (or `site_description`) becomes its meta description.
 
-## Not included (yet)
+- Search above the sidebar (see below).
+- Callouts: `!!! note`, `!!! warning`, `!!! tip` and the other admonition kinds are colored callouts (TagBrush.css 1.2 and later). Turn on the `admonition` Markdown extension, or MkDocs leaves them as plain text.
 
-- Search: MkDocs' search plugin needs theme JavaScript. Add `plugins: []` to skip building its index.
-- Admonitions (`!!! note`) show as plain text until TagBrush.css styles them.
+## Search
+
+- `search: titles` (the default) puts a search box above the sidebar that finds pages and their sections by title as you type. The theme writes a list of every page and `##` section into each page, and TagAction filters it, so there's no index to build and no script of its own. It needs TagAction 0.3 or later, and like everything TagAction adds, it's hidden when JavaScript is off. MkDocs' own search plugin isn't used; add `plugins: []` to skip building its index.
+- `search: pagefind` searches the full text with [Pagefind](https://pagefind.app/), which builds a static index after MkDocs: run `npx pagefind --site site` after `mkdocs build`. The theme loads Pagefind's search box from `pagefind/` and marks each page's article as the text to index.
+- `search: false` leaves search out.
 
 ## Tested
 

themes/mkdocs/mkdocs_tagkit/main.html

@@ -20,6 +20,11 @@
 {%- if config.theme.tagaction != false %}
 <script src="https://cdn.jsdelivr.net/npm/tagaction@0/tagaction.min.js" defer></script>
 {%- endif %}
+{%- set search = config.theme.search %}
+{%- if search == 'pagefind' %}
+<link rel="stylesheet" href="{{ 'pagefind/pagefind-ui.css'|url }}">
+<script src="{{ 'pagefind/pagefind-ui.js'|url }}" defer></script>
+{%- endif %}
 {%- for path in config.extra_css %}
 <link rel="stylesheet" href="{{ path|url }}">
 {%- endfor %}
@@ -31,6 +36,28 @@
 <body>
 {%- if nav|length > 1 %}
 <aside>
+  {%- if search == 'pagefind' %}
+  <search id="pagefind-search" data-pagefind-ui></search>
+  <script type="module">
+    addEventListener('DOMContentLoaded', () => new PagefindUI({ element: '#pagefind-search', showSubResults: true, showImages: false }));
+  </script>
+  {%- elif search and config.theme.tagaction != false %}
+  {#- Search by page and section title: TagAction filters this list as you type.
+      Both are hidden without JavaScript, where the sidebar is the way around. #}
+  <search>
+    <input type="search" aria-label="Search the docs" aria-controls="tagkit-search" hidden>
+  </search>
+  <nav aria-label="Search results">
+  <ul id="tagkit-search" hidden>
+    {%- for doc in nav.pages %}
+    <li><a href="{{ doc.url|url }}">{{ doc.title }}</a></li>
+    {%- for entry in doc.toc %}{% for section in ([entry] if entry.level == 2 else entry.children) %}
+    <li><a href="{{ doc.url|url }}{{ section.url }}">{{ doc.title }}: {{ section.title }}</a></li>
+    {%- endfor %}{% endfor %}
+    {%- endfor %}
+  </ul>
+  </nav>
+  {%- endif %}
   <nav aria-label="Documentation">
     {%- with items = nav %}{% include "nav.html" %}{% endwith %}
   </nav>
@@ -54,7 +81,7 @@
     </nav>
   </aside>
   {%- endif %}
-  <article>
+  <article{% if search == 'pagefind' %} data-pagefind-body{% endif %}>
     {{ page.content }}
     {%- if page.edit_url %}
     <p><small><a href="{{ page.edit_url }}">Edit this page</a></small></p>

themes/mkdocs/mkdocs_tagkit/mkdocs_theme.yml

@@ -4,3 +4,4 @@ static_templates:
 locale: en
 primary_color: null   # brand color for links and buttons, for example "#0f766e"
 tagaction: true       # false leaves out the TagAction script
+search: titles        # titles: search page and section titles (needs TagAction); pagefind: full text with Pagefind; false: no search