A lightweight client-side search implementation for the Permaweb Glossary. This application runs entirely in the browser using pure JavaScript, HTML, and CSS, with the FlexSearch
library for fast and efficient search capabilities.
- π Fuzzy search - find relevant terms even with typos or partial matches
- π Fully client-side - no server-side processing required
- β‘ Fast search with debouncing for optimal performance
- π± Responsive design for mobile and desktop devices
- π·οΈ Displays categories and related terms for better context
- β¨οΈ Keyboard navigation support with arrow keys
permaweb-glossary-search/
βββ public/ # Public-facing files
β βββ index.html # Main HTML entry point
βββ src/ # Source code
β βββ css/ # Stylesheets
β β βββ style.css # Main stylesheet
β βββ js/ # JavaScript files
β β βββ main.js # Main application logic
β β βββ keyboard-nav.js # Keyboard navigation functionality
β βββ data/ # Data files
β βββ glossary.json # Glossary data
βββ server.js # Development server
βββ package.json # Project configuration
βββ README.md # Project documentation
- A modern web browser (Chrome, Firefox, Safari, Edge)
- Bun for local development (optional)
-
Clone this repository:
git clone <repository-url> cd permaweb-glossary-search
-
Install dependencies:
bun install
-
Start the development server:
bun dev
-
Open your browser and navigate to
http://localhost:3000
.
To create a production build:
bun run build
This will create a dist
directory with all the necessary files for deployment.
- The application uses FlexSearch, a lightweight full-text search library with fuzzy matching capabilities.
- During initialization, the application:
- Fetches the glossary data from
src/data/glossary.json
- Creates a FlexSearch index with the glossary terms, definitions, and metadata
- Builds a context map to enhance search relevance with related terms
- Fetches the glossary data from
- When you type a search query:
- The application generates variations of your query to handle typos and related forms
- Searches across all fields (term, definition, aliases)
- Calculates relevance scores based on exact matches, partial matches, and context
- Displays the most relevant results sorted by score
Edit the src/data/glossary.json
file to add, modify, or remove terms. The JSON structure is as follows:
[
{
"term": "Term name",
"definition": "Term definition",
"category": "Category name",
"related": ["Related term 1", "Related term 2"],
"aliases": ["alias1", "alias2"],
"docs": ["https://documentation-link.com"]
}
]
-
Build the project:
bun run build
-
Place the contents of the
dist
directory on your web server. -
Add an iframe to your site:
<div class="glossary-search"> <iframe src="https://glossary_tiny4vr.permagate.io/" width="100%" height="600px" frameborder="0"></iframe> </div>
The glossary supports extensive color customization through URL parameters. This is especially useful when embedding the glossary in different websites with varying color schemes.
Add these parameters to the iframe URL to customize the colors:
?bg-color=%23121212&text-color=%23e0e0e0&link-color=%238ab4f8
Note: Color values must be URL-encoded (e.g., #
becomes %23
).
Parameter | Description | Default |
---|---|---|
bg-color |
Background color | #ffffff |
text-color |
Main text color | #111111 |
link-color |
Hyperlink color | #3498db |
border-color |
Border color | #000000 |
hover-bg |
Background color on hover | #f0f0f0 |
category-bg |
Category badge background | #f0f0f0 |
category-text |
Category badge text | #555555 |
input-bg |
Search input background | Same as bg-color |
result-bg |
Search results background | Same as bg-color |
result-hover |
Search results hover background | Same as hover-bg |
heading-color |
Heading text color | Same as text-color |
tag-bg |
Related tag background | Same as border-color |
tag-text |
Related tag text | Same as bg-color |
button-bg |
Button background | Same as border-color |
button-text |
Button text | Same as bg-color |
accent-color |
Accent color for highlights | #4a90e2 |
secondary-text |
Secondary text color | #666666 |
In addition to color customization, you can control UI elements visibility:
Parameter | Description | Values | Default |
---|---|---|---|
hide-header |
Hide the glossary header | true , 1 , or false |
false |
translucent |
Make background translucent | true , 1 , or a value between 0-1 for opacity |
Not applied |
Example with UI parameters:
?hide-header=true&translucent=0.8&bg-color=%23121212
?bg-color=%23121212&text-color=%23e0e0e0&link-color=%238ab4f8&border-color=%23333333&hover-bg=%23222222&heading-color=%23ffffff
?bg-color=%23000000&text-color=%23ffffff&link-color=%23ffff00&border-color=%23ffffff&heading-color=%23ffff00
?bg-color=%23002b36&text-color=%23839496&link-color=%23268bd2&heading-color=%23b58900
?bg-color=%230d1117&text-color=%23c9d1d9&link-color=%2358a6ff&tag-bg=%23238636&heading-color=%23f0f6fc
- The application loads quickly as it uses a lightweight search library
- The search responds immediately as you type
- For larger glossaries (hundreds of terms), the application remains performant
MIT
- FlexSearch - For the fast and fuzzy search capabilities