A document viewer with fuzzy match incremental search, built on Electron.
Chemrtron is the modern implementation of Chemr, designed for high-speed documentation access with a unified interface.
- Chemrtron: The project codename and repository name for this Electron-based implementation.
- Chemr: The product name. The application executable and system identity use this name.
- ~/.chemr: The configuration and cache directory used by the application.
- On-demand Indexing: Create and update search indexes for various documentation sets.
- Incremental Search: Fast, fuzzy-match search across all your enabled documents.
- Unified UI: A consistent experience whether you're browsing MDN, Node.js docs, or custom sets.
- System Integration: Supports system light/dark modes and global shortcuts.
- WebContentsView: Uses Electron's modern view system for seamless document rendering alongside the search UI.
Indexers are simple JavaScript files that define how to crawl and index a documentation site.
- Built-in Indexers: Located in
src/indexers/. These are bundled with the application and synchronized to~/.chemr/builtin-indexers/at runtime. - User Indexers: Can be placed in
~/.chemr/indexers/for personal use.
Example indexer structure:
export default {
id: 'my-docs',
name: 'My Documentation',
color: '#42b883',
testSpec: {
expectedSymbols: ['MyMainFunction'],
minEntries: 10
},
async index(ctx) {
// Use ctx.fetchDocument, ctx.pushIndex, etc.
}
}- Node.js (Latest LTS recommended)
- npm or yarn
# Clone the repository
git clone https://github.com/cho45/Chemrtron.git
cd Chemrtron
# Install dependencies
npm installnpm run devBuilt-in indexers (in src/indexers/) are synchronized to ~/.chemr/builtin-indexers/ when the application starts.
If you modify files in src/indexers/ and want to apply the changes immediately during development without restarting the app, run the following command:
npm run sync-indexersYou can run a live health check for built-in indexers. This script connects to the actual documentation sites to verify that the indexing logic still works against the current remote content.
# Test all indexers
npx tsx test/indexers/live-runner.ts
# Test a specific indexer (less load on remote sites)
npx tsx test/indexers/live-runner.ts luaThe runner verifies:
- Connection and retrieval of documentation pages.
- Minimum number of extracted entries.
- Presence of essential symbols (e.g.,
printfor Lua). - Validity of generated URLs (no double slashes, starts with
https://).
Chemrtron uses a modern Electron architecture leveraging WebContentsView for high-performance document rendering.
- Main Process: Handles window management, system settings, global shortcuts, and executes indexers. It also manages the
WebContentsViewlifecycle and bounds. - Renderer Process (Vue 3 + Pinia): Renders the application UI (sidebar, search panel, modals). It communicates user intent to the Main process.
- Communication: Strictly typed IPC channels defined in
src/shared/types.ts.
Chemrtron uses WebContentsView (the successor to BrowserView) to render external documentation. This ensures that heavy documentation pages do not affect the performance of the search UI and provides native scroll/navigation behavior.
Layout Strategy:
- Placeholder Element: The Vue renderer places a
<div class="view-placeholder">element in the layout where the documentation should appear. - Geometry Sync: A
ResizeObservermonitors this placeholder. Whenever its size or position changes, the renderer sends the new bounds to the Main process via IPC (update-view-bounds). - Native Resizing: The Main process resizes the
WebContentsViewto match the placeholder's coordinates exactly.
UI Design Implications:
Since WebContentsView is a native surface rendered independently of the HTML DOM, it is difficult to overlay HTML content (like a floating search bar) on top of it.
- Sidebar Search: To avoid z-index conflicts, the search interface is designed as a persistent sidebar that "pushes" the content view aside, rather than floating over it.
- Modals: When a full-screen modal (e.g., Settings) is opened, the application explicitly hides the
WebContentsViewto allow the HTML modal to be visible.
Key Components:
src/main: Main process logic (settings, cache, indexers).src/renderer: Vue-based search and settings UI.src/shared: Shared types and the fuzzy search algorithm.src/indexers: Built-in indexer definitions.
To build the application for your current platform:
npm run buildThis uses electron-builder to generate production-ready packages in the dist directory.
Releases are automated via GitHub Actions. To publish a new version:
# This will bump the patch version, create a git tag, and push to GitHub
npm run releaseThe GitHub Action will automatically:
- Build the application for Windows, macOS, and Linux.
- Create a new GitHub Release.
- Upload the installers and binaries to the release.
- Generate release notes based on commit history.
Note for macOS users: Since the app is not signed with an Apple Developer certificate, macOS may report that the app "is damaged and can't be opened" after downloading. To fix this, move the app to your /Applications folder and run the following command in your terminal:
sudo xattr -rd com.apple.quarantine /Applications/Chemrtron.appThen you can open the app normally (you may still need to Right-click and select "Open" for the first time).
MIT