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 build system has been streamlined for simplicity and maintainability:
- Clean: Removes previous build artifacts
- Copy: Copies static assets from
public/
and source files - Minify: Bundles and minifies JavaScript/CSS using Bun's built-in bundler
- Post-process: Runs optimizations including:
- Generates
glossary.txt
fromglossary.json
- Minifies JSON data
- Compresses all assets with gzip
- Generates
bun run dev
- Development server with hot reload (via preview-server.js)bun run build
- Production buildbun run preview
- Preview production build locally (via preview-server.js)bun run clean
- Clean build artifactsbun run deploy
- Deploy to production (via GitHub Actions)bun run deploy:preview
- Create preview deployment
The project uses GitHub Actions for automated deployments:
- Trigger:
bun run deploy
(creates PR or pushes tomain
branch) - URL: https://glossary.ar.io
- ArNS:
glossary
(main domain)
- Trigger:
bun run deploy:preview
(pushes topreview
branch) - URL: https://preview_glossary.ar.io
- ArNS:
glossary
withpreview
undername
Both deployments use the same GitHub Actions workflow - no local secrets needed! π
- Contributors: Use
bun run deploy:preview
β test changes β create PR to main - Maintainers: Use
bun run deploy
β choose PR or direct push based on repo governance
- Trigger: Pull requests to
main
- Action: Build verification only (no deployment)
To create a preview deployment from any branch:
# Using the npm script (recommended)
bun run deploy:preview
# Or using the script directly
./scripts/deploy-preview.sh
# Or manually
git push origin HEAD:preview --force-with-lease
The script will:
- Check for uncommitted changes
- Push your current branch to the
preview
branch - Trigger the GitHub Actions workflow
- Deploy to
https://preview_glossary.ar.io
To deploy to production from any branch:
# Deploy to production (interactive menu)
bun run deploy
The script will offer two deployment options:
-
Create Pull Request (recommended for most workflows)
- Pushes your current branch to origin
- Provides GitHub URL to create PR to main
- Production deployment happens when PR is merged
-
Direct Push to Main (maintainers only)
- Pushes directly to main branch
- Triggers immediate production deployment
- Use only if you have write access to main
This approach works with both protected and unprotected main branches.
- 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