algolia / algolia/sphinx-docsearch
Feat Request: Native custom button support
- 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
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