How to add a custom search engine to Firefox

I thought it would be trivial to add a custom search engine to Firefox. To be fair, it is fairly trivial, but not quite as easy as navigating to the correct Firefox settings page and adding a new entry. Instead, I found the process to be somewhat hidden and less obvious.

Firefox uses the OpenSearch description format to add search engines, which Mozilla describes as:

The OpenSearch description format can be used to describe the web interface of a search engine. This allows a website to describe a search engine for itself, so that a browser or other client application can use that search engine. OpenSearch is supported by (at least) Firefox, Edge, Safari, and Chrome. (See Reference Material for links to other browsers' documentation.)

The MDN docs then go on to describe the XML OpenSearch description file and how autodiscovery works with websites and plugins.

Having read all this, I set off to find a real world example of an OpenSearch description file that I could easily bastardise for my own use. The following is offered by YouTube:

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
    <ShortName>YouTube</ShortName>
    <Description>Search for videos on YouTube</Description>
    <Tags>youtube video</Tags>
    <Image height="16" width="16" type="image/vnd.microsoft.icon">https://www.youtube.com/favicon.ico</Image>
    <Url type="text/html" template="https://www.youtube.com/results?search_query={searchTerms}&page={startPage?}&utm_source=opensearch"></Url>
    <Query role="example" searchTerms="cat"></Query>
</OpenSearchDescription>

I modified the file to suit my needs and added it to the website that provides my custom search. I then added the following link element to the head element of the same website:

<link rel="search" type="application/opensearchdescription+xml" href="/path/to/opensearch.xml" title="Custom Search">

With this in place, I was able to add the custom search to Firefox via the Search input in the toolbar (I don't normally have this item in my toolbar, so I had to add it first). After adding my new custom search engine, I was able to set it as the default via the Firefox settings page about:preferences#search.

Now, any query that I enter into Firefox's address bar is passed through to my own custom search engine. And, I feel like I have gained control over one of the most important input boxes on my computer.

P.S. I call it my own "custom search engine" in this post to match the terminology used by Mozilla. In reality it is a PHP script that does a lookup on the query and sends a response. There is no search index of content. I should probably write a post about it at some point.

P.P.S. I've recently been using/testing Vivaldi browser, in which the process is much easier. Adding a new search engine can be achieved directly within the Settings -> Search page. That said, I have experienced issues in Vivaldi whereby the newly created search engine setting does not always remain as the default search option when set, reverting back to Google. This could be due to an account syncing issue?!