Browser docs

Modal Mode

Hugo Modules Authors September 25, 2023 4 min read Search Modules Modal

Guide to install the search module in modal mode.

On this page

Please make sure you have meet the requirements.

Examples

There is an example site and it’s source code to help you get started.

There also a guide for integrating Docsy with the search module.

Import the module

hugo.yaml

1module:
2  imports:
3  - path: github.com/hugomods/search

hugo.toml

1[module]
2[[module.imports]]
3    path = 'github.com/hugomods/search'

hugo.json

1{
2   "module": {
3      "imports": [
4         {
5            "path": "github.com/hugomods/search"
6         }
7      ]
8   }
9}

Base Template

You should specify the lang and dir attributes on <html> tag of base template (layouts/_default/baseof.html by default), so that the module can recognize and render in current page language.

1<html
2  lang="{{ .Lang }}"
3  {{ with .Language.LanguageDirection }}dir="{{ . }}"{{ end }}>
4  <!-- ... -->
5</html>

Include the CSS

There are multiple approaches to include the CSS.

Include the CSS via Hugo Pipes

Recommended when you’re using Hugo pipes to build CSS from source, it combines your styles and search styles into one bundle file, which is helpful to reduce the HTTP requests.

 1{{/* NOTE: we must change the CSS target to separate the style between LTR and RTL sites. */}}
 2{{/* Otherwise, Hugo may treats it as the same style (cached). */}}
 3{{/* Ignore it if your themes and sites aren't going to support RTL. */}}
 4{{ $rtl := eq .Language.LanguageDirection "rtl" }}
 5{{ $cssTarget := cond $rtl "css/main.rtl.css" "css/main.css" }}
 6{{ $css := resources.Get "main.scss" | toCSS }}
 7{{/* If you have a prebuilt CSS, replace the $css with the following. */}}
 8{{ $css := resources.Get "main.css" }}
 9{{ $searchCSS := partial "search/assets/css-resource" . }}
10{{ $css = slice $searchCSS $css | resources.Concat $cssTarget }}
11<link rel="stylesheet" href="{{ $css.RelPermalink }}" />
  • The main.scss/main.css is your styles file, which located in the assets folder, replace it with yours.
  • Note that slice $searchCSS $css puts the $css after $searchCSS, so that $css style can override the search’s.
  • The search/assets/css-resource is a partial that returns a search CSS resource.

Import the CSS via SCSS File

1@import "search/scss/index";

This way is more complex than the former, you’ll need to take care of the PostCSS, Autoprefixer and RTLCSS. See how CSS resource partial does.

Include the CSS via Partial

This approach generates a <link> tag.

1{{ partial "search/assets/css" . }}

Include the JavaScript

We can achieve this via two ways.

Include the JavaScript via Hugo Pipes

Recommended when you’re using Hugo pipes to build JS from source, it combines your JS and search JS into one bundle file, which is helpful to reduce the HTTP requests.

1{{ $js := resources.Get "main.ts" | js.Build }}
2{{/* If you have a prebuilt JS file, use the following instead. */}}
3{{ $js := resources.Get "main.js" }}
4{{ $searchJS := partial "search/assets/js-resource" . }}
5{{ $js = slice $js $searchJS | resources.Concat "js/main.js" }}
6<script src="{{ $js.RelPermalink }}" defer></script>

Please note that you should not set the async attribute on the script.

  • The main.ts/main.js is your JavaScript file, which located in the assets folder, replace it with yours.
  • The search/assets/js-resource is a partial that returns a search JS resource.

Include the JavaScript via Partial

This partial will generate a <script> tag.

1{{ partial "search/assets/js" . }}

Create Modal Toggle Buttons

This step is optional, you’re still be able to open the search modal by shortcuts (default to CTRL + K), but I recommend adding such a toggle button for getting better user experience, because users are not aware of these shortcuts.

Adjust the button to your theme UI, place it wherever you like, for example,

1<button class="search-modal-toggle">Search</button>
  • The toggle button can be any HTML tag, not just the button, since the module will listen the click event on the HTML elements have the modal_toggle_selector specified class name (default to .search-modal-toggle), this also means that the page can contain multiple toggle buttons.

Set Up the Search Indices

Append the SearchIndex formats into outputs.home.

hugo.yaml

1outputs:
2  home:
3  - HTML
4  - RSS
5  - SearchIndex

hugo.toml

1[outputs]
2  home = ['HTML', 'RSS', 'SearchIndex']

hugo.json

1{
2   "outputs": {
3      "home": [
4         "HTML",
5         "RSS",
6         "SearchIndex"
7      ]
8   }
9}