DocSearch
Doks comes with FlexSearch preconfigured out of the box. If you want to use DocSearch in stead, this guide will explain how.
Set up DocSearch
To follow this guide, you’ll need an existing Doks site and a DocSearch project.
If a file does not exist in your projects’ root, copy the file over from node_modules/@hyas/doks-core/
. Make sure to use the same directory structure in your root.
Add parameters
Add the following parameters to config/_default/params.toml
:
# Add-ons
[add_ons]
docSearch = true # false (default) or true
# Doks (@hyas/doks-core)
[doks]
# FlexSearch
flexSearch = false # true (default) or false
Install dependencies
DocSearch provides a UI component, bundled as JavaScript and CSS packages. You’ll need both of these packages to display the widget:
This will install the required dependencies.
Add buttons
Add to layouts/partials/header/header.html
buttons for mobile and desktop to trigger the DocSearch modal.
Button mobile
Add (around line 38) after <!-- FlexSearch mobile -->
:
Button mobile
<!-- DocSearch mobile -->
{{ if site.Params.add_ons.docSearch -}}
<div id="docsearch" class="d-none" tabindex="-1" aria-disabled="true"></div>
<button type="button" id="searchToggleMobile" class="btn btn-link nav-link mx-2 d-lg-none" aria-label="Search website">
<svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-search" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
<path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
<circle cx="10" cy="10" r="7"></circle>
<line x1="21" y1="21" x2="15" y2="15"></line>
</svg>
</button>
{{ end -}}
Button desktop
Add (around line 170) after <!-- FlexSearch desktop -->
:
Button desktop
<!-- DocSearch desktop -->
{{ if site.Params.add_ons.docSearch -}}
<button type="button" id="searchToggleDesktop" class="btn btn-link nav-link mx-2 d-none d-lg-block" aria-label="Search website">
<svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-search" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
<path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
<circle cx="10" cy="10" r="7"></circle>
<line x1="21" y1="21" x2="15" y2="15"></line>
</svg>
</button>
{{ end -}}
Add script
Create script
Add the following to assets/js/docsearch.js
and update with your appId
, indexName
, and apiKey
:
import docsearch from "@docsearch/js";
docsearch({
container: "#docsearch",
appId: "YOUR_APP_ID",
indexName: "YOUR_INDEX_NAME",
apiKey: "YOUR_SEARCH_API_KEY",
insights: true
});
const onClick = function () {
document.getElementsByClassName("DocSearch-Button")[0].click();
};
document.getElementById("searchToggleMobile").onclick = onClick;
document.getElementById("searchToggleDesktop").onclick = onClick;
Load script
Add to layouts/partials/footer/script-footer-custom.html
:
{{ if site.Params.add_ons.docSearch -}} {{ partial "footer/esbuild" (dict "src" "js/docsearch.js" "load" "async" "transpile" false) -}} {{ end -}}
Add styles
Create variables
Add to assets/scss/common/_variables-docsearch.scss
and (optionally) override:
Variables DocSearch
/* DocSearch Variables */
:root {
--docsearch-primary-color: rgb(84, 104, 255);
--docsearch-text-color: rgb(28, 30, 33);
--docsearch-spacing: 12px;
--docsearch-icon-stroke-width: 1.4;
--docsearch-highlight-color: var(--docsearch-primary-color);
--docsearch-muted-color: rgb(150, 159, 175);
--docsearch-container-background: rgba(101, 108, 133, 0.8);
--docsearch-logo-color: rgba(84, 104, 255);
/* modal */
--docsearch-modal-width: 560px;
--docsearch-modal-height: 600px;
--docsearch-modal-background: rgb(245, 246, 247);
--docsearch-modal-shadow: inset 1px 1px 0 0 rgba(255, 255, 255, 0.5), 0 3px 8px 0 rgba(85, 90, 100, 1);
/* searchbox */
--docsearch-searchbox-height: 56px;
--docsearch-searchbox-background: rgb(235, 237, 240);
--docsearch-searchbox-focus-background: #fff;
--docsearch-searchbox-shadow: inset 0 0 0 2px var(--docsearch-primary-color);
/* hit */
--docsearch-hit-height: 56px;
--docsearch-hit-color: rgb(68, 73, 80);
--docsearch-hit-active-color: #fff;
--docsearch-hit-background: #fff;
--docsearch-hit-shadow: 0 1px 3px 0 rgb(212, 217, 225);
/* key */
--docsearch-key-gradient: linear-gradient(-225deg, rgb(213, 219, 228) 0%, rgb(248, 248, 248) 100%);
--docsearch-key-shadow: inset 0 -2px 0 0 rgb(205, 205, 230), inset 0 0 1px 1px #fff, 0 1px 2px 1px rgba(30, 35, 90, 0.4);
--docsearch-key-pressed-shadow: inset 0 -2px 0 0 #cdcde6, inset 0 0 1px 1px #fff, 0 1px 1px 0 rgba(30, 35, 90, 0.4);
/* footer */
--docsearch-footer-height: 44px;
--docsearch-footer-background: #fff;
--docsearch-footer-shadow: 0 -1px 0 0 rgb(224, 227, 232), 0 -3px 6px 0 rgba(69, 98, 155, 0.12);
}
/* Darkmode */
html[data-bs-theme="dark"] {
--docsearch-text-color: rgb(245, 246, 247);
--docsearch-container-background: rgba(9, 10, 17, 0.8);
--docsearch-modal-background: rgb(21, 23, 42);
--docsearch-modal-shadow: inset 1px 1px 0 0 rgb(44, 46, 64), 0 3px 8px 0 rgb(0, 3, 9);
--docsearch-searchbox-background: rgb(9, 10, 17);
--docsearch-searchbox-focus-background: #000;
--docsearch-hit-color: rgb(190, 195, 201);
--docsearch-hit-shadow: none;
--docsearch-hit-background: rgb(9, 10, 17);
--docsearch-key-gradient: linear-gradient(-26.5deg, rgb(86, 88, 114) 0%, rgb(49, 53, 91) 100%);
--docsearch-key-shadow: inset 0 -2px 0 0 rgb(40, 45, 85), inset 0 0 1px 1px rgb(81, 87, 125), 0 2px 2px 0 rgba(3, 4, 9, 0.3);
--docsearch-key-pressed-shadow: inset 0 -2px 0 0 #282d55, inset 0 0 1px 1px #51577d, 0 1px 1px 0 #0304094d;
--docsearch-footer-background: rgb(30, 33, 54);
--docsearch-footer-shadow: inset 0 1px 0 0 rgba(73, 76, 106, 0.5), 0 -4px 8px 0 rgba(0, 0, 0, 0.2);
--docsearch-logo-color: rgb(255, 255, 255);
--docsearch-muted-color: rgb(127, 132, 151);
}
Update styles
Add to assets/scss/common/_custom.scss
:
Custom styles
// DocSearch
.DocSearch-Container {
z-index: 2000 !important;
}
.DocSearch-Hit-icon {
display: flex;
align-items: center;
}
.DocSearch-Hits mark {
padding: 0;
}
@media (max-width: 768px) {
.DocSearch-Modal {
position: fixed !important;
}
}
Load styles
Add (around line 98) to assets/scss/app.scss
after // 9. Custom styles
:
// 10. DocSearch
@import "common/variables-docsearch";
@import "@docsearch/css/dist/modal";
Update PurgeCSS
In config/postcss.config.js
update dynamicAttributes
and ...whitelister
:
module.exports = {
plugins: [
purgecss({
dynamicAttributes: ["aria-selected"],
safelist: [...whitelister(["./node_modules/@docsearch/css/dist/modal.css"])]
})
]
};