Create "global search" solution

[marble]

• https://github.com/TYPO3-Documentation/T3DOCS-elasticsearch-logic admin is @nito-web
• https://github.com/TYPO3-Documentation/T3DOCS-elasticsearch-frontend admin is @nito-web
• https://github.com/TYPO3-Documentation/T3DOCS-elasticsearch-indexing admin is @nito-web

Related: #4

[DanielSiepmann]

We also check docsearch of Algolia: https://community.algolia.com/docsearch/

@DanielSiepmann is in contact and evaluates this.

The following are requirements: https://community.algolia.com/docsearch/who-can-apply.html https://community.algolia.com/docsearch/required-configuration.html

Looks like a sitemap would be helpful, this might also be helpful for Google / SEO. I've found https://github.com/jdillard/sphinx-sitemap which might do the job.

Current state: I've contact Algolia via Discord and applied for participation via form and am waiting for getting contacted.

[DanielSiepmann]

Following the configuration, we might already provide some of these aspects. E.g. Algolia provides some CSS Classes for better crawling, we already have those, with different names:

.toBeIndexed -> .DocSearch-content

Headline selectos:
selectors.lvl0.selector would be .wy-breadcrumbs li:nth-child(2)
selectors.lvl1 -> .toBeIndexed h1
selectors.lvl2 -> .toBeIndexed h2
selectors.lvl3 -> .toBeIndexed h3
selectors.lvl4 -> .toBeIndexed h4
selectors.lvl5 -> .toBeIndexed h5
selectors.lvl6 -> .toBeIndexed h6
selectores.text -> .toBeIndexed p, .toBeIndexed div

Right now the following is not provided by us:

Every DOM elements matching the lvlX selectors must have a unique id or name attribute. This will help the redirection to directly scroll down to the exact place of the matching elements. These attributes defined the right anchor to use.

Instead we have an surrounding HTML tag with an ID.

Our crawler automatically extract information from our DocSearch specific meta tags:

Might be a problem for us to provide those. Even if we can add them to the theme, we would need to re render all manuals. Maybe we can just asume "en" for now.

We instead provide:

  <meta name="book-name"    content="TYPO3 Core APIs"/>
  <meta name="book-version" content="7.6"/>

Maybe this can be used, also as headline 1 the book-name should be used.

[DanielSiepmann]

Algolia already setup a search. The configuration is available here: https://github.com/algolia/docsearch-configs/blob/master/configs/typo3.json and can be adjusted via pull requests.

We have also access to the Analytics part of Algolia, through my account. Once we decide to go with this solution, I'm sure we can add further accounts.

I've to check the integration and results.

[DanielSiepmann]

I've added a new folder at https://stage.docs.typo3.com/search/ where Algolia is now integrated. One can already get a small sneak peak about the search results. NOTE I've adjusted only the startpage (Index.html).

We need to fix the styling. Right now the results are cut off on the right side, due to the sidebar width.

I'll also have a chat with Algolia in the future about where we want to go and about our needs.

[sypets]

Will it be possible to select the TYPO3 version when searching?

[DanielSiepmann]

That's one feature we want to include. Right now the main goal was to provide a very basic first integration, so we can improve and discuss things.

Further Documentation related to the tasks:

• https://github.com/algolia/autocomplete.js#global-options
• https://community.algolia.com/docsearch/behavior.html#autocompleteoptions
• https://community.algolia.com/docsearch/required-configuration.html#introduces-global-information-as-meta-tags

Thanks to @justusmoroni we have a basic working css integration for desktop.

We also need to provide some more CSS to make the search usaeable in further situation:

• Mobile.
• Desktop scrolled to the bottom of a page.

[DanielSiepmann]

I've created https://github.com/TYPO3-Documentation/WIP-Algolia-Docsearch-Integration as repository to keep track of implementation details and necessary changes.

[DanielSiepmann]

New information after our call with Algolia Docsearch:

It's free, we need to display the logo.
Crawling will happen every 24 hours.

[DanielSiepmann]

I'll collect Open Questions here and send them to algolia:

• Can we trigger re indexing? E.g. if core team publishes a new release with new documentation.

[alexander-nitsche]

Since there is now t3docs-search-indexer for searching the TYPO3 documentation, is the work in this topic generally necessary any longer, and are these repos and URLs of particular use:

1. https://github.com/TYPO3-Documentation/WIP-Algolia-Docsearch-Integration
2. https://stage.docs.typo3.com/search/
3. https://github.com/algolia/docsearch-configs/blob/master/configs/typo3.json

or can they be cleaned up?

[DanielSiepmann]

I didn't continue. Work was made based on a budget and small group of people.
I'm fine with closing this issue as we already have a search now, which has its own setup regarding issues.

https://github.com/TYPO3-Documentation/WIP-Algolia-Docsearch-Integration can be archived / removed as it is no longer used.
https://stage.docs.typo3.com/search/ can not be resolved.
https://github.com/algolia/docsearch-configs/blob/master/configs/typo3.json resolved to a 404.

[alexander-nitsche]

Ok. I would vote for deleting instead of archiving (1) as there are rather small changes made to CSS and TSConfig which may be of no use in years when a return to Algolia might come into play and when their API probably has changed in meantime. What do you think?

[DanielSiepmann]

Sure :) Go ahead

[alexander-nitsche]

Ok, these repositories have been deleted in favor of using t3docs-search-indexer instead:

1. https://github.com/TYPO3-Documentation/T3DOCS-elasticsearch-logic
2. https://github.com/TYPO3-Documentation/T3DOCS-elasticsearch-frontend
3. https://github.com/TYPO3-Documentation/T3DOCS-elasticsearch-indexing
4. https://github.com/TYPO3-Documentation/WIP-Algolia-Docsearch-Integration

[alexander-nitsche]

Can this issue be closed?