%

Hugo: Opensearch

Article published the ; modified the
3 minutes to read

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

Description

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.

Documentation

the Hugo official documentation:

the Opensearch official documentation:

Configuration

  • the main config file: config.toml

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

MediaType

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

Hugo >= 0.20

Since Hugo 0.20, you need to add:

[mediaTypes]
    [mediaTypes."application/opensearchdescription+xml"]
    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:

[mediaTypes]
    [mediaTypes."application/opensearchdescription+xml"]
    suffixes = ["xml"]
Tip

OuputFormat

The output format declaration to add:

[outputs]
    [outputFormats.OpenSearch]
    baseName = "opensearch"
    isHTML = false
    isPlainText = false
    mediaType = "application/opensearchdescription+xml"
    noUgly = true

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

[outputs]
    home = ["HTML", "OpenSearch"]

Template

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.
Info
{{ 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>
	<InputEncoding>utf-8</InputEncoding>
	<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>
	<OutputEncoding>UTF-8</OutputEncoding>
	<ShortName>Websearch</ShortName>
	<SyndicationRight>open</SyndicationRight>
	<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" />
</OpenSearchDescription>

autodiscovery

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

Warning

Atom

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" />

HTML

Add a link element:

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

RSS

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" />

Acknowledgments

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