Add search facet: main chapters of documentation (#2063)

* Add search facet: main chapters of documentation
* Enhance layout search form

Author: ksuess

docs/_static/documentation.css

@@ -15,3 +15,55 @@ a:not([title="(in Plone Documentation v6)"]).reference.external::after {
   font: var(--fa-font-solid);
   font-size: .75em;
 }
+
+/* Search form styling */
+.bd-search {
+  max-width: 600px;
+}
+
+.bd-search .input-group-text {
+  background-color: var(--pst-color-surface);
+  border-color: var(--pst-color-border);
+  color: var(--pst-color-text-muted);
+}
+
+.bd-search .form-control,
+.bd-search .form-select {
+  border-color: var(--pst-color-border);
+  background-color: var(--pst-color-surface);
+  color: var(--pst-color-text-base);
+}
+
+.bd-search .form-control:focus,
+.bd-search .form-select:focus {
+  border-color: var(--pst-color-primary);
+  box-shadow: 0 0 0 0.2rem rgba(var(--pst-color-primary-rgb), 0.25);
+}
+
+.bd-search .form-label {
+  font-weight: 500;
+  color: var(--pst-color-text-base);
+}
+
+.bd-search .search-button__kbd-shortcut kbd {
+  background-color: var(--pst-color-text-muted);
+  color: var(--pst-color-surface);
+  padding: 0.1rem 0.3rem;
+  border-radius: 3px;
+  font-size: 0.85em;
+}
+
+.bd-search-container ul.search {
+  padding-inline-start: 0;
+}
+
+/* Search results styling */
+#search-results .breadcrumbs {
+  font-size: 0.85em;
+  color: var(--pst-color-text-muted);
+  margin-bottom: 0.25rem;
+}
+
+#search-results .breadcrumbs .pathseparator {
+  padding: 0 0.5em;
+}

docs/_static/searchtools.js

@@ -244,6 +244,7 @@ if (typeof splitQuery === "undefined") {
 const Search = {
   _index: null,
   _queued_query: null,
+  _queued_section: null,
   _pulse_status: -1,
 
   htmlToText: (htmlString, anchor) => {
@@ -272,10 +273,15 @@ const Search = {
 
   init: () => {
     const query = new URLSearchParams(window.location.search).get("q");
+    const section = new URLSearchParams(window.location.search).get("section");
+    const select = document
+      .querySelector('select[name="section"]')
     document
       .querySelectorAll('input[name="q"]')
       .forEach((el) => (el.value = query));
-    if (query) Search.performSearch(query);
+    if (section) select.value = section;
+    else select.value = "all";
+    if (query) Search.performSearch(query, section);
   },
 
   loadIndex: (url) =>
@@ -285,14 +291,19 @@ const Search = {
     Search._index = index;
     if (Search._queued_query !== null) {
       const query = Search._queued_query;
+      const section = Search._queued_section;
       Search._queued_query = null;
-      Search.query(query);
+      Search._queued_section = null;
+      Search.query(query, section);
     }
   },
 
   hasIndex: () => Search._index !== null,
 
-  deferQuery: (query) => (Search._queued_query = query),
+  deferQuery: (query, section) => {
+    Search._queued_query = query;
+    Search._queued_section = section;
+  },
 
   stopPulse: () => (Search._pulse_status = -1),
 
@@ -310,7 +321,7 @@ const Search = {
   /**
    * perform a search for something (or wait until index is loaded)
    */
-  performSearch: (query) => {
+  performSearch: (query, section) => {
     // create the required interface elements
     const searchText = document.createElement("h2");
     searchText.textContent = _("Searching");
@@ -335,8 +346,8 @@ const Search = {
     Search.startPulse();
 
     // index already loaded, the browser was quick!
-    if (Search.hasIndex()) Search.query(query);
-    else Search.deferQuery(query);
+    if (Search.hasIndex()) Search.query(query, section);
+    else Search.deferQuery(query, section);
   },
 
   _parseQuery: (query) => {
@@ -475,10 +486,16 @@ const Search = {
     return results.reverse();
   },
 
-  query: (query) => {
+  query: (query, section) => {
     const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query);
-    const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms);
-    const qresults = results;
+    let results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms);
+
+    // Filter results by section
+    if (section && section !== 'all') {
+      results = results.filter(result => {
+        return result[0].split('/')[0] === section;
+      });
+    }
 
     // for debugging
     //Search.lastresults = results.slice();  // a copy

docs/_templates/components/search-field.html

@@ -0,0 +1,49 @@
+{# A bootstrap-styled field that will direct to the `search.html` page when submitted #}
+<form class="bd-search mt-3 mb-5 p-3"
+      action="{{ pathto('search') }}"
+      method="get">
+  <div class="input-group">
+    <input type="search"
+           class="form-control"
+           name="q"
+           id="search-input"
+           placeholder="{{ theme_search_bar_text }}"
+           aria-label="{{ theme_search_bar_text }}"
+           autocomplete="off"
+           autocorrect="off"
+           autocapitalize="off"
+           spellcheck="false"/>
+    <button class="btn btn-primary" type="submit">
+      <i class="fa-solid fa-magnifying-glass"></i>
+    </button>
+    <!-- <span class="input-group-text search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span> -->
+  </div>
+  <div class="facet mt-3">
+    <label for="section" class="form-label">Filter by section</label>
+    <select class="form-select" name="section" id="section" onchange="this.form.submit()">
+      <option value="all">All sections</option>
+      {% for id, title in
+        [
+          ['admin-guide', 'Admin Guide'],
+          ['backend', 'Backend'],
+          ['classic-ui', 'Classic UI'],
+          ['conceptual-guides', 'Conceptual Guides'],
+          ['contributing', 'Contributing'],
+          ['deployment', 'Deployment'],
+          ['developer-guide', 'Developer Guide'],
+          ['i18n-l10n', 'i18n/l10n'],
+          ['install', 'Install'],
+          ['overview', 'Overview'],
+          ['reference-guide', 'Reference Guide'],
+          ['training', 'Training'],
+          ['upgrade', 'Upgrade'],
+          ['user-guide', 'User Guide'],
+          ['plone.restapi', 'Plone REST API'],
+          ['plone.api', 'Plone API'],
+          ['volto', 'Volto'],
+        ] %}
+        <option value="{{id}}">{{ title }}</option>
+      {% endfor %}
+    </select>
+  </div>
+</form>