boost/website-v2-docs
2
0
Fork 0
mirror of https://github.com/boostorg/website-v2-docs.git synced 2026-01-19 04:42:17 +00:00
Code Issues Projects Releases Wiki Activity

Add description for client-side approach

Browse Source 
close #48
This commit is contained in:
Mohammad
2023-05-05 14:15:51 +00:00
committed by Vinnie Falco
parent 2f7f5fc895
commit 33a4b17c1f
1 changed files with 21 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
doc/search-functionality.adoc
View File

@@ -1,14 +1,28 @@
= Search Functionality
This document describes the requirements and design of search functionality across Boost site documentation generated by Antora.
== Client-Side Search
With a client-side approach, a search index is built during the process of building a static website and will be loaded along the page inside the browser. A Javascript search engine running inside the browser uses this search index to respond to the search queries so there is no server-side service involved.
Client-side search has some advantages over server-based search:
* It is very responsive because there is no request/response involved in the search process.
* There is no need for a server-side database and keep it updated with new content.
* Low maintenance cost because there is no load on the server to respond to search queries.
* It can work offline (considering that we can build reference documents offline)
== research
=== Antora Lunr Extension
https://gitlab.com/antora/antora-lunr-extension[Antora Lunr Extension] indexes the content during the build and includes the index in the published site, which is then used to provide a client-side full-text search.
Pros:
* Easy Integeration with Antora (minor changes to `playbook.yaml` and `header-content.hbs`).
* Easy Integration with Antora (minor changes to `playbook.yaml` and `header-content.hbs`).
* No need for a server-side service and works offline.
* Very responsive due to the fact there is no request/response and everything happens inside the browser.
@@ -18,6 +32,8 @@ Cons:
* No option for adding metadata for categorizing search results in reference documentation.
* No semantic search.
NOTE: Antora Lunr Extension is already integrated into the demo site https://docs.cppalliance.org/user-guide/index.html
=== Server-Side Solutions
==== DocSearch
@@ -36,13 +52,13 @@ Needs investigation (https://typesense.org/[link-to-website]).
==== Docs.rs
Open source documentation host for crates of the Rust Programming Language.
Open-source documentation host for crates of the Rust Programming Language.
It uses a custom client-side search solution for searching in Reference Documentation. engine and indexing tools are implemented in https://github.com/rust-lang/rust/tree/master/src/librustdoc[librustdoc].
The search-index seems to contain meta-data for identifier types:
The search index seems to contain meta-data for identifier types:
[,javascript]
[, Javascript]
----
const itemTypes = [
"mod",
@@ -57,5 +73,5 @@ const itemTypes = [
The search results are being narrowed down into Names, Parameters, and Return Types. Example of the search page (searching `socket` in `Tokio` library): https://docs.rs/tokio/1.28.0/tokio/?search=socket
The `search-index.js`file for each crate is not loaded until the user clicks on the search bar to reduce the size of the page.
The `search-index.js` file for each crate is not loaded until the user clicks on the search bar to reduce the size of the page.