Skip to content

dpshade/permaweb-glossary

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

97 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Permaweb Glossary Search

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.

Features

  • πŸ” 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

Project Structure

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

Getting Started

Prerequisites

  • A modern web browser (Chrome, Firefox, Safari, Edge)
  • Bun for local development (optional)

Running Locally

  1. Clone this repository:

    git clone <repository-url>
    cd permaweb-glossary-search
  2. Install dependencies:

    bun install
  3. Start the development server:

    bun dev
  4. Open your browser and navigate to http://localhost:3000.

Building for Production

To create a production build:

bun run build

This will create a dist directory with all the necessary files for deployment.

How It Works

  1. The application uses FlexSearch, a lightweight full-text search library with fuzzy matching capabilities.
  2. 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
  3. 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

Customizing the Glossary

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"]
  }
]

Embedding in Other Sites

  1. Build the project:

    bun run build
  2. Place the contents of the dist directory on your web server.

  3. 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>

Color Customization

The glossary supports extensive color customization through URL parameters. This is especially useful when embedding the glossary in different websites with varying color schemes.

Basic Color Parameters

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).

Available Color Parameters

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

UI Visibility Parameters

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

Example Color Schemes

Dark Mode

?bg-color=%23121212&text-color=%23e0e0e0&link-color=%238ab4f8&border-color=%23333333&hover-bg=%23222222&heading-color=%23ffffff

High Contrast

?bg-color=%23000000&text-color=%23ffffff&link-color=%23ffff00&border-color=%23ffffff&heading-color=%23ffff00

Solarized Dark

?bg-color=%23002b36&text-color=%23839496&link-color=%23268bd2&heading-color=%23b58900

GitHub-inspired

?bg-color=%230d1117&text-color=%23c9d1d9&link-color=%2358a6ff&tag-bg=%23238636&heading-color=%23f0f6fc

Performance Considerations

  • 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

License

MIT

Credits

  • FlexSearch - For the fast and fuzzy search capabilities

About

OSS glossary of the permaweb, consisting of terms related to: Arweave, AO, AR.IO, HyperBEAM, etc.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •