Hugo: Opensearch

Article published the ; modified the
3 minutes to read

This article has 471 words.
RAW source of the article:
Commit version: 5ed7c38


Opensearch is a collection of simple formats for the sharing of search results on your website.

Most browsers web will offer you to add your site as a search engine, you need to manage the autodiscovery .

Hugo, by default, not manage Opensearch. We are going to modify the configuration to create a new custom output format.


the Hugo official documentation:

the Opensearch official documentation:


  • the main config file: config.toml

It’s necessary to modify this file config to create a new:


The related MimeType to the Opensearch description format is: application/opensearchdescription+xml.

Hugo >= 0.20

Since Hugo 0.20, you need to add:

    suffix = "xml"

Here, we added a new type of format for the mime type: application/opensearchdescription+xml, with the extension name: xml.

Hugo >= 0.44

Since Hugo 0.44, you need to add:

    suffixes = ["xml"]


The output format declaration to add:

    baseName = "opensearch"
    isHTML = false
    isPlainText = false
    mediaType = "application/opensearchdescription+xml"
    noUgly = true

Next, you need to add "OpenSearch" at your home variable:

    home = ["HTML", "OpenSearch"]


Simply, create the template as layouts/_default/index.opensearch.xml.

  • If your site is multilingual, the alternates links to the version of language are generated.

{{ printf `<?xml version="1.0" encoding="utf-8" ?>` | safeHTML }}
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/" xmlns:ie="http://schemas.microsoft.com/Search/2008/" xmlns:moz="http://www.mozilla.org/2006/browser/search/">
	<Attribution>© {{ $.Date.Format "2006" | safeHTML }} {{ site.Author.name }}; http://creativecommons.org/publicdomain/zero/1.0/legalcode.{{ site.Language.Lang }}</Attribution>
	<Contact>{{ site.Author.email | safeHTML }}</Contact>
	<Description>{{ i18n "opensearchDescription" }}</Description>
	<Developer>{{ site.Author.name | safeHTML }}</Developer>
	<Image width="64" height="64" type="image/png">{{ site.BaseURL }}img/Logo-64px.png</Image>
	<Image width="16" height="16" type="image/vnd.microsoft.icon">{{ site.BaseURL }}img/favicon.ico</Image>
	<Language>{{ site.LanguageCode }}</Language>
	<LongName>{{ site.Title }} :: {{ site.Language.Lang }}</LongName>
	<ie:PreviewUrl type="text/html" method="GET" template="{{ site.BaseURL }}{{ site.Language.Lang }}/tags/{searchTerms}/"/>
	<moz:SearchForm>{{ site.BaseURL }}{{ site.Language.Lang }}/tags/{searchTerms}/</moz:SearchForm>
	<Url template="{{ site.BaseURL }}{{ site.Language.Lang }}/tags/{searchTerms}/" type="text/html" />
	<Url rel="self" template="{{ site.BaseURL }}opensearch.xml" type="application/opensearchdescription+xml" />


The autodiscovery is the method to inform the web clients about the Opensearch format description in your web site.



If you have modified your Hugo configuration to generate an Atom feed, you will need to modify it to add the following:

<link href="{{ site.BaseURL }}/opensearch.xml" rel="search" type="application/opensearchdescription+xml" title="Websearch" />


Add a link element:

<link rel="search" href="/opensearch.xml" title="Websearch" type="application/opensearchdescription+xml">


If you generate your RSS feed, make sure to edit it, to add:

  • the xmlns:atom="http://www.w3.org/2005/Atom" attribute, into your rss element:
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  • in order to declarate atom:link item, as:
<atom:link href="{{ site.BaseURL }}/opensearch.xml" rel="search" type="application/opensearchdescription+xml" title="Websearch" />


Once again, a thruly thank you @solene who introduced me to Opensearch.