---
date: 2020-04-14T16:54:07+02:00
description: "Howto set up the Opensearch description format into Hugo!"
draft: false
tags: ["Hugo", "Opensearch", "search"]
title: "Hugo: Opensearch"
translationKey: "hugo-opensearch"
---

## 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 {{<anchor autodiscovery autodiscovery >}}. 
 
**Hugo**, by default, not manage Opensearch. We are going to modify the {{< anchor configuration configuration >}} 
to create a new custom output format. 

## Documentation

the Hugo official documentation:

* {{< gohugo n="output-formats" s="templates" >}}

the Opensearch official documentation:

* https://github.com/dewitt/opensearch/blob/master/opensearch-1-1-draft-6.md

## Configuration

* the main config file: `config.toml`

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

- {{< anchor "Media Type" "mediatype" >}}
- {{< anchor "Output Format" "ouputformat" >}}
- {{< anchor Template "template" >}} for the Opensearch file.

### MediaType

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

#### Hugo >= 0.20

Since Hugo 0.20, you need to add:

```toml
[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:

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

{{< note tip >}}If your old configuration was before the v0.44, you have to transform the variable `suffix` to `suffixes = ['xml']` ! {{< /note >}}

### OuputFormat

The output format declaration to add:

```toml
[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:

```toml
[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.

----

{{<note info>}}ATTENTION: the presented template manages a multilingual 
website. {{</note>}}

```xml
{{ 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. 

{{< note warning >}}Make sure that the value of the `title` attribute matches that of the `ShortName` element!{{</note>}}

### Atom

If you have modified your Hugo configuration to generate an {{< inside2 a="atom" l="web:hugo:hugo-feed" t="Atom" >}} feed, 
you will need to modify it to add the following:

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

### HTML

Add a `link` element: 

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

### RSS

If you generate your {{< inside2 a="rss" l="web:hugo:hugo-feed" t="RSS" >}} feed, 
make sure to edit it, to add: 

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

----

## Acknowledgments

Once again, a thruly thank you @[solene](https://dataswamp.org/~solene/) who introduced me to Opensearch.

----