swadhin / opengrammar public

swadhinbiswas

[email protected]
2026-03-14 19:11:43 +0600 committed NaN years ago
0f406e3
commit 0f406e3
1 file changed
+453 -0
Showing 1 changed file+453-0
docs/04-browser-extension-setup.md
▼docs/04-browser-extension-setup.md
+453-0
@@ -0,0 +1,453 @@
1
+# 🌐 Browser Extension Setup Guide
2
+
3
+Install and configure OpenGrammar on Chrome, Brave, Edge, and Firefox.
4
+
5
+---
6
+
7
+## 📋 Supported Browsers
8
+
9
+| Browser | Version | Status |
10
+|---------|---------|--------|
11
+| **Google Chrome** | 88+ | ✅ Fully Supported |
12
+| **Brave** | 1.20+ | ✅ Fully Supported |
13
+| **Microsoft Edge** | 88+ | ✅ Fully Supported |
14
+| **Mozilla Firefox** | 90+ | ✅ Supported (Temporary) |
15
+| **Opera** | 74+ | ✅ Supported |
16
+| **Vivaldi** | 3.6+ | ✅ Supported |
17
+
18
+---
19
+
20
+## 🔧 Installation
21
+
22
+### Google Chrome
23
+
24
+#### Step 1: Build the Extension
25
+```bash
26
+# Navigate to extension folder
27
+cd opengrammar/opengrammar/extension
28
+
29
+# Install dependencies
30
+bun install
31
+
32
+# Build for production
33
+bun run build
34
+```
35
+
36
+This creates a `dist/` folder with the built extension.
37
+
38
+#### Step 2: Load in Chrome
39
+1. Open Chrome
40
+2. Navigate to `chrome://extensions/`
41
+3. Enable **Developer mode** (toggle in top-right corner)
42
+4. Click **Load unpacked**
43
+5. Select the `opengrammar/extension/dist` folder
44
+6. Click **Select**
45
+
46
+✅ **Extension loaded!** You'll see the OpenGrammar icon in your toolbar.
47
+
48
+#### Step 3: Pin to Toolbar (Optional)
49
+1. Click the puzzle piece icon (Extensions) in toolbar
50
+2. Find OpenGrammar in the list
51
+3. Click the pin icon 📌
52
+
53
+---
54
+
55
+### Brave Browser
56
+
57
+#### Step 1: Build the Extension
58
+Same as Chrome:
59
+```bash
60
+cd opengrammar/opengrammar/extension
61
+bun install
62
+bun run build
63
+```
64
+
65
+#### Step 2: Load in Brave
66
+1. Open Brave
67
+2. Navigate to `brave://extensions/`
68
+3. Enable **Developer mode** (top-right)
69
+4. Click **Load unpacked**
70
+5. Select `opengrammar/extension/dist` folder
71
+6. Click **Select**
72
+
73
+✅ **Extension loaded!**
74
+
75
+#### Step 3: Pin to Toolbar
76
+1. Click the puzzle piece icon
77
+2. Pin OpenGrammar
78
+
79
+---
80
+
81
+### Microsoft Edge
82
+
83
+#### Step 1: Build the Extension
84
+Same as Chrome:
85
+```bash
86
+cd opengrammar/opengrammar/extension
87
+bun install
88
+bun run build
89
+```
90
+
91
+#### Step 2: Load in Edge
92
+1. Open Edge
93
+2. Navigate to `edge://extensions/`
94
+3. Enable **Developer mode** (left sidebar)
95
+4. Click **Load unpacked**
96
+5. Select `opengrammar/extension/dist` folder
97
+6. Click **Select Folder**
98
+
99
+✅ **Extension loaded!**
100
+
101
+#### Step 3: Pin to Toolbar
102
+1. Click the puzzle piece icon
103
+2. Pin OpenGrammar
104
+
105
+---
106
+
107
+### Mozilla Firefox
108
+
109
+⚠️ **Note:** Firefox support is temporary. The extension must be reloaded each time you restart Firefox.
110
+
111
+#### Step 1: Build the Extension
112
+```bash
113
+cd opengrammar/opengrammar/extension
114
+bun install
115
+bun run build
116
+```
117
+
118
+#### Step 2: Load in Firefox
119
+1. Open Firefox
120
+2. Navigate to `about:debugging#/runtime/this-firefox`
121
+3. Click **Load Temporary Add-on**
122
+4. Navigate to `opengrammar/extension/dist`
123
+5. Select `manifest.json`
124
+6. Click **Open**
125
+
126
+✅ **Extension loaded!**
127
+
128
+⚠️ **Important:** This extension will be unloaded when you close Firefox. You'll need to reload it each session.
129
+
130
+---
131
+
132
+### Opera
133
+
134
+#### Step 1: Enable Chrome Extensions
135
+1. Open Opera
136
+2. Go to Settings
137
+3. Enable "Allow extensions from other stores"
138
+
139
+#### Step 2: Install Chrome Extension Loader
140
+1. Visit Opera Add-ons
141
+2. Search for "Install Chrome Extensions"
142
+3. Add to Opera
143
+
144
+#### Step 3: Load OpenGrammar
145
+1. Navigate to `chrome://extensions/`
146
+2. Enable Developer mode
147
+3. Load unpacked → `opengrammar/extension/dist`
148
+
149
+---
150
+
151
+### Vivaldi
152
+
153
+#### Step 1: Load in Vivaldi
154
+1. Open Vivaldi
155
+2. Navigate to `vivaldi://extensions/`
156
+3. Enable **Developer mode**
157
+4. Click **Load unpacked**
158
+5. Select `opengrammar/extension/dist`
159
+
160
+---
161
+
162
+## ⚙️ Initial Configuration
163
+
164
+### Step 1: Open Settings
165
+1. Click the OpenGrammar icon in your toolbar
166
+2. Click the **Settings** (gear) icon
167
+
168
+### Step 2: Configure Backend URL
169
+1. Find **Backend URL** field
170
+2. Enter your backend URL:
171
+ - Local: `http://localhost:8787`
172
+ - Cloudflare: `https://opengrammar.yourname.workers.dev`
173
+ - Vercel: `https://opengrammar-backend.vercel.app`
174
+ - Railway: `https://your-app.railway.app`
175
+ - Render: `https://opengrammar-backend.onrender.com`
176
+ - Docker: `http://localhost:8787`
177
+
178
+### Step 3: Configure AI Provider
179
+1. Select **Provider** from dropdown:
180
+ - **Groq** (Recommended - Free tier)
181
+ - **OpenAI** (Best quality)
182
+ - **OpenRouter** (100+ models)
183
+ - **Together AI** (Open-source)
184
+ - **Ollama** (Local, offline)
185
+ - **Custom** (Your own API)
186
+
187
+2. Enter your **API Key** (if required)
188
+3. Select **Model** from dropdown
189
+
190
+### Step 4: Test Connection
191
+1. Look for the **status indicator**
192
+2. 🟢 Green = Connected
193
+3. 🔴 Red = Not connected
194
+
195
+### Step 5: Save Settings
196
+Click **Save** to apply changes.
197
+
198
+---
199
+
200
+## 🎯 Provider Recommendations
201
+
202
+### For Free Usage
203
+**Provider:** Groq
204
+- **API Key:** Get free key at [console.groq.com](https://console.groq.com)
205
+- **Model:** `llama-3.1-70b-versatile`
206
+- **Limits:** 100 requests/day free
207
+
208
+### For Best Quality
209
+**Provider:** OpenAI
210
+- **API Key:** Get at [platform.openai.com](https://platform.openai.com)
211
+- **Model:** `gpt-4o-mini`
212
+- **Cost:** ~$0.15 per 1K requests
213
+
214
+### For Privacy (Offline)
215
+**Provider:** Ollama (Local)
216
+- **API Key:** (none required)
217
+- **Model:** `qwen2.5:1.5b`
218
+- **Setup:** See [Docker Self-Hosting](06-docker-self-hosting.md)
219
+
220
+### For Model Variety
221
+**Provider:** OpenRouter
222
+- **API Key:** Get at [openrouter.ai](https://openrouter.ai)
223
+- **Models:** 100+ options (Claude, Llama, etc.)
224
+- **Cost:** Pay-per-use
225
+
226
+---
227
+
228
+## 🔍 Verifying Installation
229
+
230
+### Test 1: Check Extension Icon
231
+1. Click the OpenGrammar icon
232
+2. Popup should open
233
+3. You should see settings and status
234
+
235
+### Test 2: Check Grammar
236
+1. Open any text box (Gmail, Google Docs, etc.)
237
+2. Type: `me and him went to store`
238
+3. You should see a **red underline** under "me and him"
239
+
240
+### Test 3: Check Backend Connection
241
+1. Click extension icon
242
+2. Look for status indicator
243
+3. Should be green with "Connected"
244
+
245
+### Test 4: Test Rewrite Feature
246
+1. Select any text on a webpage
247
+2. Right-click
248
+3. Choose **Rewrite with OpenGrammar**
249
+4. Rewrite popup should open
250
+
251
+---
252
+
253
+## 🛠️ Extension Features
254
+
255
+### Popup Menu
256
+Accessed by clicking the toolbar icon:
257
+- **Enable/Disable Toggle** - Turn extension on/off
258
+- **Error Count** - Shows detected issues
259
+- **Settings** - Open settings page
260
+- **Statistics** - View writing stats
261
+- **Backend Status** - Connection indicator
262
+
263
+### Settings Page
264
+Right-click extension icon → **Options**:
265
+
266
+#### General Settings
267
+- Enable OpenGrammar
268
+- Check as you type
269
+- Show notifications
270
+- Keyboard shortcuts
271
+
272
+#### AI Settings
273
+- Provider selection
274
+- API key management
275
+- Model selection
276
+- Custom base URL
277
+- Backend health check
278
+
279
+#### Site-Specific Settings
280
+- Disable on specific domains
281
+- Per-domain AI settings
282
+- Domain whitelist
283
+
284
+#### Custom Dictionary
285
+- Add custom words
286
+- Import/export dictionary
287
+- Manage false positives
288
+
289
+#### Ignored Issues
290
+- View ignored suggestions
291
+- Clear all ignored issues
292
+- Manage per-domain ignores
293
+
294
+#### Data Management
295
+- Export all settings
296
+- Import settings backup
297
+- Reset to defaults
298
+
299
+---
300
+
301
+## 🎨 User Interface
302
+
303
+### Color-Coded Underlines
304
+
305
+| Color | Meaning | Example |
306
+|-------|---------|---------|
307
+| **Red** | Grammar/Spelling | "teh" → "the" |
308
+| **Amber** | Clarity Issues | Long, confusing sentences |
309
+| **Blue** | Style Suggestions | Passive voice, weak words |
310
+
311
+### Interactive Tooltips
312
+Click any underlined text to see:
313
+- Issue type icon
314
+- Original text
315
+- Suggested fix
316
+- Explanation
317
+- Action buttons (Apply, Ignore, Add to Dictionary)
318
+
319
+### Rewrite Popup
320
+Accessed via right-click or `Ctrl+Shift+R`:
321
+- Selected text preview
322
+- 8 tone buttons
323
+- Rewrite button
324
+- Apply/Copy buttons
325
+- Close button
326
+
327
+---
328
+
329
+## 🔄 Updating the Extension
330
+
331
+### Manual Update
332
+```bash
333
+# Rebuild extension
334
+cd opengrammar/opengrammar/extension
335
+bun run build
336
+
337
+# Reload in browser
338
+# chrome://extensions/ → Click reload icon on OpenGrammar
339
+```
340
+
341
+### Automatic Updates
342
+Since this is a locally-loaded extension, it won't auto-update. You need to:
343
+1. Rebuild manually
344
+2. Reload in extensions page
345
+
346
+---
347
+
348
+## 🆘 Troubleshooting
349
+
350
+### Extension Not Showing
351
+**Problem:** Can't find OpenGrammar icon
352
+
353
+**Solution:**
354
+1. Check `chrome://extensions/` (or browser equivalent)
355
+2. Make sure extension is enabled
356
+3. Click the puzzle piece icon → Pin OpenGrammar
357
+
358
+### No Grammar Highlights
359
+**Problem:** Typing errors but no underlines appear
360
+
361
+**Solution:**
362
+1. Check extension is enabled (icon badge visible)
363
+2. Verify site is not in disabled domains
364
+3. Check backend is running: `curl http://localhost:8787/health`
365
+4. Reload the page
366
+5. Check browser console (F12) for errors
367
+
368
+### Backend Not Connecting
369
+**Problem:** Red status indicator, "Not connected" error
370
+
371
+**Solution:**
372
+1. Verify backend URL in settings
373
+2. Test backend: `curl your-backend-url/health`
374
+3. Check CORS configuration
375
+4. Restart backend service
376
+5. Check firewall settings
377
+
378
+### Extension Crashes
379
+**Problem:** Extension closes or stops working
380
+
381
+**Solution:**
382
+1. Reload extension in extensions page
383
+2. Clear browser cache
384
+3. Check browser console for errors
385
+4. Rebuild extension
386
+5. Try in incognito mode (enable in extensions page)
387
+
388
+### Rewrite Not Working
389
+**Problem:** Right-click menu doesn't appear
390
+
391
+**Solution:**
392
+1. Make sure text is selected
393
+2. Check extension is enabled
394
+3. Reload the page
395
+4. Check browser permissions
396
+5. Try keyboard shortcut: `Ctrl+Shift+R`
397
+
398
+### Settings Not Saving
399
+**Problem:** Settings reset after closing
400
+
401
+**Solution:**
402
+1. Check browser storage permissions
403
+2. Clear browser data for extension
404
+3. Try in a fresh browser profile
405
+4. Export settings before resetting
406
+
407
+---
408
+
409
+## 📊 Browser-Specific Notes
410
+
411
+### Chrome
412
+- ✅ Best compatibility
413
+- ✅ All features work
414
+- ⚠️ Requires Developer mode for local loading
415
+
416
+### Brave
417
+- ✅ Same as Chrome (Chromium-based)
418
+- ✅ Privacy features don't interfere
419
+- ⚠️ May need to disable Shields for some sites
420
+
421
+### Edge
422
+- ✅ Full Chromium compatibility
423
+- ✅ All features work
424
+- ⚠️ Some Microsoft-specific UI differences
425
+
426
+### Firefox
427
+- ⚠️ Temporary loading only
428
+- ⚠️ Must reload each session
429
+- ✅ All core features work
430
+- ⚠️ Some Chrome APIs not available
431
+
432
+### Opera
433
+- ✅ Chrome extension compatibility
434
+- ⚠️ May need additional setup
435
+- ✅ All features work
436
+
437
+### Vivaldi
438
+- ✅ Full Chromium compatibility
439
+- ✅ All features work
440
+- ✅ Easy extension management
441
+
442
+---
443
+
444
+## 📚 Related Documentation
445
+
446
+- [Quick Start](01-quick-start.md) - Get started in 5 minutes
447
+- [Backend Deployment](05-backend-deployment.md) - Deploy your backend
448
+- [AI Provider Setup](07-ai-providers.md) - Configure AI providers
449
+- [Using OpenGrammar](09-using-opengrammar.md) - Daily usage guide
450
+
451
+---
452
+
453
+**Your extension is now installed and ready! Start writing better! ✨**
0
454