Tool Index is a compact home for an expanding collection of useful browser tools. It brings calculators, converters, generators, and file viewers together in one searchable directory. The initial catalog contains 55 tools organized into eight categories. Each entry explains the task in plain English and provides separate links to the working website and its source repository. The intended public home is https://yeshan-jun.github.io/, without a project name in the path.
The directory is a standalone project. It does not contain copies of the linked applications, move their files, or change their independent websites. Its job is to help someone choose a tool, understand what it does, and reach it quickly. The visual design uses a quiet paper background, a green category index, serif section headings, and compact rows with clear separators.
Visitors can browse the full collection, narrow it to one category, or search across names, descriptions, category labels, and keywords. Multiple search words must all appear somewhere in an entry. Matching is case insensitive and ignores extra spaces. A category and a search can be used together. The result count updates immediately, empty categories disappear, and an empty state offers a way to return to the complete collection.
Every tool is present in the original HTML document. JavaScript enhances an existing directory instead of downloading data and constructing a blank page after arrival. With scripts disabled, the category links jump to sections and every website link remains available. Search and category choices appear in the URL so a visitor can share a filtered view. The browser Back button restores category navigation.
Use Node.js 20 or later for maintenance commands. No package installation is necessary because the generator, preview server, and unit tests use built-in Node modules.
node scripts/build.mjs
node scripts/preview.mjsOpen http://127.0.0.1:4173/ to preview the directory. Set the PORT environment variable if another application already uses that port. The server listens on the local loopback interface. Stop it with Ctrl+C. The root index.html is already generated and can also be opened directly to browse links; use an HTTP preview for module scripts and service-worker behavior.
To add a tool, add one object to data/tools.json with id, name, description, category, keywords, url, and repository. Use a stable lowercase hyphenated ID. Write an original English description of the actual task. Set url to the verified website address rather than deriving it from a local folder name. Open Babel is an existing example where those names differ. The keywords value is an array of search terms, not one string.
To remove an entry, delete that object from the JSON array and rebuild. This removes only the navigation entry. To change a name, description, category, or link, update its existing object. Category sections and counts are generated from the data; categories follow their first appearance in the array, and tools within each category are sorted by name. Editing the generated HTML directly is discouraged because the next build replaces it.
The maintenance input is a UTF-8 JSON array. The validator requires readable names, descriptions, categories, keyword arrays, unique IDs, and unique website URLs. Website destinations must be HTTPS project addresses under yeshan-jun.github.io, and source links must be repositories under github.com/yeshan-jun. Invalid records stop the build before output is written. This deliberate restriction keeps the directory focused on this collection; change the validator and its tests if the product later includes other owners.
The output is standard HTML, CSS, JavaScript, SVG, PNG, XML, and a web app manifest. Visitors do not upload documents or enter personal account details into the directory. Individual linked tools have their own input formats and requirements.
scripts/build.mjs validates the catalog, fills templates/index.html, and writes a complete index.html. It also generates sw.js from its template with a content-based cache version. The generator escapes text for HTML and safely serializes structured data. The page includes a root canonical URL, social metadata, a CollectionPage with an ItemList, a sitemap, and nine VARIABLE comment placeholders retained for the owner's publishing process.
The browser reads searchable metadata already attached to the static rows. It does not fetch the JSON catalog, contact the GitHub API, or need a backend. The application shell can be cached for offline use after a successful visit. Network requests are preferred over cached resources. The service worker handles an explicit allowlist of directory files and leaves other project paths alone. Cache cleanup only touches the directory's own cache prefix. Offline access to this index does not make linked websites available offline.
Run npm test or node --test tests/*.test.mjs for catalog, escaping, search, static-output, and cache-policy checks. Build again after changes to the template, styles, scripts, icons, or catalog so the offline cache version reflects those changes. The build writes only generated outputs and does not remove unrelated files or Git metadata.
data/tools.json: the single maintained tool catalog.templates/: homepage and worker source templates.assets/css/: responsive directory styling.assets/js/: browser enhancement, search rules, and cache policy.assets/icons/: the directory's original SVG and raster icons.scripts/: validation, static generation, and local preview.tests/: repeatable Node tests and an optional browser-check script.docs/: design decisions, implementation plan, and verification notes.- Root HTML, manifest, worker, sitemap, and robots files: static website output.
Publishing is managed by the owner and is outside this delivery. There is no deployment workflow and no remote repository operation in this project. Serve the generated root HTML together with assets, manifest, service worker, robots file, and sitemap on a static host. There is no server application and no dist directory. Existing workspace deployment scripts were not changed. The metadata targets the GitHub user-site root, not a nested project URL.
The intended repository name is yeshan-jun.github.io. The matching local directory uses that exact name. repo.config.json records the intended root homepage and the actual source and output technologies. The repository links shown in the directory come from the known project names, while website addresses follow the verified catalog.
Searching and filtering run in the browser. There is no analytics script, advertising integration, remote search endpoint, or account system. Search terms are stored in the page URL for sharing and may appear in browser history or a static host's access logs when the URL is requested. The service worker stores only public directory resources. Following a tool or repository link navigates to that destination and its own behavior applies.
This project is released under the MIT License. See LICENSE for the complete terms. That license covers this directory's original implementation; linked applications retain their own licenses. The directory does not redistribute their source code or assets. Fonts use local system families, and the interface has no downloaded font or image dependency.
- GitHub Pages quickstart: user-site repository naming and root addresses.
- Schema.org CollectionPage: directory page semantics.
- Schema.org ItemList: the generated list of tool destinations.
- Initial catalog: the workspace's 55-project inventory and browser verification record dated September 21, 2026.