algolia / algolia/sphinx-docsearch

Feat Request: Native custom button support

Open
#64 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
21
Forks
1
Avg merge
2d 5h
Merged PRs (30d)
4

Description

Here's what I did to add a custom button to my [sphinx-book-theme](https://github.com/algolia/sphinx-docsearch/issues/62):

1. Add a `js/customAlgoliaDocSearchBtn.js` containing:

```html
// #########################################
// _static/js/customAlgoliaDocSearchBtn.js
// - This script allows .
// - This script should be loaded deferred
// - Initial template suggestion thanks from yafimvo @
// https://github.com/jupyter-book/jupyter-book/issues/1324#issuecomment-1512757574
// #########################################

// Declare the selector for the search button
const SEARCH_BUTTON_SELECTOR = '.search-button__button';
const searchButtons = document.querySelectorAll(SEARCH_BUTTON_SELECTOR);

// On click, for all search bars found, emulate CTRL+K to bring up search UI for both buttons
searchButtons.forEach(button => {
button.addEventListener('click', () => {
console.log('[js/customAlgoliaDocSearchBtn.js] Clicked search btn -> emulating CTRL+K');
const event = new KeyboardEvent('keydown', {
key: 'k',
ctrlKey: true,
bubbles: true // Allows the event to propagate up through the DOM
});
document.dispatchEvent(event);
});
});
```

2. In `conf.py`, add:

```py
html_js_files.append(("js/customAlgoliaDocSearchBtn.js", {"defer": "defer"}))
```

I forgot if I did anything else, but that's just about it. You could wrap this in your extension and allow a custom button that'll just simply trigger a `CTLR+K` to hook into your existing code. You'd just need a `conf.py` var that replaces the current `SEARCH_BUTTON_SELECTOR` for it to magically work.

Contributor guide

Open the contributing guide

Research direction

The proposal names js/customAlgoliaDocSearchBtn.js and conf.py; start by comparing those suggested changes with the extension's existing search-button integration. Define how a configurable button selector should connect to the current search UI, then build the Sphinx documentation and verify that a custom button opens search when clicked.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, python
Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.