Document how to add literature search

[MortenHofft]

The library includes literature search and so does the base theme. But it isn't documented how to add it to a site.

Currently the best option is to look at a sample implementation here

[ymgan]

Hey @MortenHofft

I would like to add literature search for our hosted portal https://hp-antarctic.gbif-staging.org/literature/search See: https://github.com/gbif/hp-antarctic/blob/master/literature/search.md?plain=1

Looking at https://github.com/gbif/hp-north-america/tree/master/literature , may I know what are these files for about.md, all.md, from.md, shared.md ? Thanks a lot!

[timrobertson100]

Hi @ymgan

Morten is on holiday, so I'll do my best... I am fairly sure these just show how you can configure the literature search with different scopes:

• all shows all literature
• from showing how to scope the search with literature authored from institutions in the listed countries
• about showing how to scope for literature that relates to the listed areas.

It's fairly common for national sites to show from/about views to satisfy different audiences, but you could very well just have one in your instance.

I hope this helps get you going. Please say if not.

[ymgan]

Thanks a lot @timrobertson100 I appreciate it!

I went to the permalink in the file, for example: https://www.gbif-north-america.org/literature/from based on permalink here but there is nothing, so I am not sure if I understand how this works

And how does the objective of having that file from.md differ from using the countriesOfResearcher filter? e.g. https://www.gbif-north-america.org/literature?countriesOfResearcher=US in this case

[timrobertson100]

Yeah, I tried the same... I'm not sure I can explain why the US site doesn't work like that I'm afraid, but I do think that was the intention of the 3 examples, using permalinks instead of those filter-like URLs

[ymgan]

Thank you for explaining Tim, I appreciate it!! We can pick that back up again when Morten is back :) It is not urgent from our end :)

[albenson-usgs]

If I'm remembering correctly, Morten did away with the "from" and "about" because it was confusing. Instead you just get one page and there are filters for country of researcher and country of coverage. Both North America and GBIF.us are like that https://www.gbif-north-america.org/literature https://www.gbif.us/literature

[albenson-usgs]

https://github.com/gbif/hosted-portals/issues/206

[ymgan]

Perfect, thank you so much @albenson-usgs !!!

[MortenHofft]

Thank you. I've added the us example to the documentation. And for anyone seeing this:

When adding a new type (e.g. dataset, dataset-search, literature-search) you need to do a couple of things.

First you should add a markdown file

---
permalink: /literature/search # This is the important as the url should be the same as the widget is configured to react to
layout: literature # important as the layout is what inserts the widget

# the rest is just the usual Frontmatter
title: Literature
description: Explore related literature
lang-ref: literature
---

And then you need to enable the literature type in routes. E.g.

var siteConfig = {
  version: 2,
  routes: {
    enabledRoutes: ['occurrenceSearch', 'literatureSearch']
  }
}

And you probably want to configure what literature items to show

var siteConfig = {
literature: {
    rootFilter: {
      predicate: {
        type: 'or', predicates: [
          {
            type: 'in',
            key: 'countriesOfResearcher',
            values: ['US', 'UM', 'AS', 'FM', 'GU', 'MH', 'MP', 'PR', 'PW', 'VI']
          },
          {
            type: 'in',
            key: 'countriesOfCoverage',
            values: ['US', 'UM', 'AS', 'FM', 'GU', 'MH', 'MP', 'PR', 'PW', 'VI']
          }
        ]
      }
    },
    highlightedFilters: ['q', 'countriesOfResearcher', 'countriesOfCoverage', 'year']
  }
}