Skip to content

Commit 6903ec1

Browse files
lucolvinlucolvin
authored
Merge pull request #2 from lucolvin/readme
2 parents 9a21c95 + e4285eb commit 6903ec1

File tree

3 files changed

+226
-89
lines changed

3 files changed

+226
-89
lines changed

‎README.md‎

Lines changed: 224 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,237 @@
1-
## Zero for Outlook (Firefox & Chrome Extension)
1+
# Zero for Outlook (Firefox & Chrome Extension)
2+
3+
Zero for Outlook adds configurable keyboard shortcuts and extends functionality of Outlook on the web, making it more efficient and enjoyable to use.
24

3-
This extension adds configurable keyboard shortcuts to Outlook on the web.
4-
The first shortcut supported is **Undo archive**, which clicks the transient **Undo** button that appears after you archive or move a message.
55
> [!CAUTION]
66
> These extensions are still in early beta and are under active development. Expect breaking changes. Use at your own risk and so on.
7-
8-
97
> [!TIP]
108
> Find a bug? Open an [issue](https://github.com/lucolvin/zero-for-outlook/issues/new/choose).
11-
129
> [!NOTE]
13-
> The docs including this README are extremely out of date. A docs site is currently being created. And will be updated [here](https://docs.zero-extension.com/)
14-
.
15-
16-
### What it does
17-
18-
- **Undo archive shortcut**
19-
- Listens for your chosen key combination (for example **Ctrl + Z** or **Alt + U**).
20-
- When pressed on an Outlook web tab (and you are _not_ typing in an input/textarea/editor), it finds the **Undo** button and clicks it for you.
21-
- It is scoped to Outlook web only:
22-
- `https://outlook.live.com/*`
23-
- `https://outlook.office.com/*`
24-
- `https://outlook.office365.com/*`
25-
26-
- **Vim-style navigation (h / j / k / l)**
27-
- When enabled, gives you a Vim-like flow for switching folders and messages:
28-
- **`h`** (or `l` from the message list) focuses and "pins" the left sidebar/folder list.
29-
- While pinned, **`j`** / **`k`** move up and down items in the sidebar.
30-
- Press **`l`** from the sidebar to move into the message list; then **`j`** / **`k`** move between messages.
31-
- In the message list, **Shift + `j`** / **Shift + `k`** act like **Shift + ↓ / Shift + ↑**, extending the current selection so you can select **multiple messages at once** and then snooze or archive them using Outlook’s own commands and commands from Zero for Outlook.
32-
- All vim keys are ignored while you are typing in an input, textarea, or rich-text editor, so they do not interfere with composing emails.
33-
- Default is **on**, but you can toggle it from the extension's options page (see **Vim-style navigation** toggle).
34-
35-
- **Snooze overlay (s)**
36-
- Press **`s`** when a message is selected to open a beautiful overlay menu for snoozing or unsnoozing.
37-
- In regular views, the overlay shows options to snooze: **Later today**, **Tomorrow**, **This weekend**, **Next week**, and **Choose a date**.
38-
- In the Scheduled folder, the overlay shows an **Unsnooze** option to move messages back to the Inbox.
39-
- Navigate with **`j`** / **`k`**, select with **Enter**, and close with **Esc** or **`s`**.
40-
- The overlay displays concrete times (e.g., "5:00 AM", "Wed 8:00 AM") when Outlook provides them.
41-
42-
- **Settings / options page**
43-
- Lets you capture a keyboard shortcut by pressing the keys directly.
44-
- Lets you toggle vim-style navigation on/off, including **Shift + j / Shift + k multi-select** behavior in the message list.
45-
- Lets you enable a dark, glassy theme for the options page and snooze/unsnooze overlay.
46-
- Shows brief information on how the extension behaves, on which domains it runs, and how vim-style navigation and multi-select work.
47-
- Accessible by clicking the extension icon in your browser's toolbar, or by right-clicking the extension icon and selecting "Options".
48-
49-
### Privacy / data collection
50-
51-
- The extension **never collects or sends any email content or browsing data**.
52-
- There is **no analytics or telemetry** and no external network requests from the extension code.
53-
- The only data stored is your chosen shortcut and whether vim navigation and dark mode are enabled, kept in the browser’s extension storage and used locally to handle key presses.
54-
55-
### Files overview
56-
57-
- **`zero-for-outlook-chrome/manifest.json`**: Manifest V3 configuration for the Chrome extension.
58-
- **`zero-for-outlook-firefox/manifest.json`**: Manifest V2 configuration for the Firefox extension (with `browser_specific_settings` for Gecko).
59-
- **`contentScript.js`**: Injected into Outlook web; listens for the configured shortcut and clicks the **Undo** button, handles vim-style navigation, and manages the snooze overlay.
60-
- **`options.html` / `options.js` / `options.css`**: Options page UI and logic; stores the shortcut, vim toggle, and dark mode toggle in `storage.sync`.
61-
62-
The same code structure is duplicated for both the Chrome and Firefox versions of the extension, under `zero-for-outlook-chrome` and `zero-for-outlook-firefox`.
63-
64-
### Loading in Chrome (Developer Mode)
65-
66-
1. Run Chrome and open `chrome://extensions`.
67-
2. Enable **Developer mode** (top-right toggle).
68-
3. Click **Load unpacked** and select the `zero-for-outlook-chrome` folder:
69-
- `/path/to/folder/zero-for-outlook/zero-for-outlook-chrome`
70-
4. Open Outlook on the web in a tab, archive an email, and when the **Undo** bar appears, press your configured shortcut to test.
71-
5. Try pressing **`s`** on a selected message to test the snooze overlay, or use **`j`** / **`k`** to navigate messages if vim navigation is enabled.
72-
73-
### Loading in Firefox (Temporary Add-on)
74-
75-
1. Run Firefox and open `about:debugging#/runtime/this-firefox`.
76-
2. Click **Load Temporary Add-on…**.
77-
3. Select the `manifest.json` file in the Firefox folder:
78-
- `/path/to/folder/zero-for-outlook/zero-for-outlook-firefox/manifest.json`
79-
4. Open Outlook on the web and test the shortcut the same way as in Chrome.
80-
5. Try pressing **`s`** on a selected message to test the snooze overlay, or use **`j`** / **`k`** to navigate messages if vim navigation is enabled.
81-
82-
### Customizing / extending
83-
84-
- To add more shortcuts (for other actions in Outlook web), you can:
85-
- Extend the storage schema (e.g., `archiveShortcut`, `markReadShortcut`, etc.).
86-
- Add more keyboard handlers and DOM queries in `contentScript.js` for the relevant buttons/elements.
87-
- Expand the options UI to configure those additional shortcuts and toggles.
88-
89-
### Automated versioning
10+
> The docs including this README are extremely out of date. A docs site is currently being created. And will be updated at [the docs site](https://docs.zero-extension.com/)
11+
12+
## What it does
13+
14+
Zero for Outlook provides a comprehensive set of keyboard shortcuts and features to enhance your Outlook web experience:
15+
16+
### Core Shortcuts
17+
18+
- **Undo archive shortcut** (default: `Z`)
19+
- Triggers Outlook's built-in **Undo** after archiving or moving a message
20+
- Configurable via the options page
21+
- Only active when you're not typing in an input/textarea/editor
22+
23+
- **Command bar** (default: `Cmd/Ctrl + K`)
24+
- Superhuman-style command palette for quick access to all features
25+
- Search and execute commands with keyboard navigation
26+
- Press `Esc` or click outside to close
27+
28+
### Vim-Style Navigation
29+
30+
When enabled, provides Vim-like navigation for folders and messages:
31+
32+
- **`h`** (or `l` from the message list) focuses and "pins" the left sidebar/folder list
33+
- While pinned, **`j`** / **`k`** move up and down items in the sidebar
34+
- Press **`l`** from the sidebar to move into the message list; then **`j`** / **`k`** move between messages
35+
- In the message list, **Shift + `j`** / **Shift + `k`** act like **Shift + ↓ / Shift + ↑**, extending the current selection so you can select multiple messages at once
36+
- All vim keys are ignored while typing in inputs, textareas, or rich-text editors
37+
- Default is **on**, can be toggled from the options page
38+
39+
### Snooze Overlay
40+
41+
- Press **`s`** when a message is selected to open a beautiful overlay menu for snoozing or unsnoozing
42+
- In regular views, shows options to snooze: **Later today**, **Tomorrow**, **This weekend**, **Next week**, and **Choose a date**
43+
- In the Scheduled folder, shows an **Unsnooze** option to move messages back to the Inbox
44+
- Navigate with **`j`** / **`k`**, select with **Enter**, and close with **Esc** or **`s`**
45+
- Displays concrete times (e.g., "5:00 AM", "Wed 8:00 AM") when Outlook provides them
46+
47+
### Command Bar Actions
48+
49+
The command bar (`Cmd/Ctrl + K`) provides quick access to:
50+
51+
- **Message Actions**
52+
- Undo last action
53+
- Summarize current email (requires Gemini API key)
54+
- Unsubscribe (finds and clicks unsubscribe links)
55+
- Snooze presets (Later today, Tomorrow, This weekend, Next week)
56+
- Unsnooze
57+
58+
- **Navigation**
59+
- Focus sidebar
60+
- Focus message list
61+
- Open Calendar
62+
- Open Inbox/Mail
63+
- Open Bookings
64+
- Open To Do
65+
- Open Outlook settings
66+
67+
- **Extension Settings**
68+
- Toggle dark mode
69+
- Toggle celebration (inbox zero overlay)
70+
- Hide/show Outlook options bar
71+
- Open Zero for Outlook options page
72+
- Add custom shortcut (element picker)
73+
74+
- **Custom Shortcuts**
75+
- All your custom shortcuts appear in the command bar
76+
- Can be executed directly from the command bar
77+
78+
### AI Features (Optional)
79+
80+
- **Email Summarization** (requires Gemini API key)
81+
- Uses Google's Gemini API to summarize email conversations
82+
- Focuses on key decisions, requests, dates, and next steps
83+
- Accessible via command bar or shortcut
84+
85+
- **AI Title Editing** (requires Gemini API key)
86+
- When creating custom shortcuts, optionally use AI to generate better names and descriptions
87+
- Helps format keyboard shortcut names for UI elements
88+
- Can be toggled on/off in options
89+
90+
### Custom Shortcuts
91+
92+
- Create keyboard shortcuts for any button or element on screen
93+
- Use the element picker (accessible from command bar) to select elements
94+
- Optionally use AI to generate better names and descriptions
95+
- All custom shortcuts appear in the command bar
96+
- Manage all custom shortcuts from the options page
97+
98+
### Additional Features
99+
100+
- **Dark Mode**: Glassy, dark theme for overlays and options page
101+
- **Inbox Zero Celebration**: Optional fireworks/celebration overlay when your inbox reaches zero
102+
- **Options Bar Toggle**: Hide/show Outlook's options bar and header for a cleaner interface
103+
- **Multi-select Support**: Use Shift+j/k in vim mode to select multiple messages
104+
105+
### Privacy / Data Collection
106+
107+
- The extension **never collects or sends any email content or browsing data**
108+
- There is **no analytics or telemetry** and no external network requests from the extension code (except when using optional AI features)
109+
- **AI Features**: When using Gemini API features (email summarization or AI title editing), your content is sent to Google's Gemini API. This requires you to provide your own API key, which is stored locally in your browser's extension storage
110+
- The only data stored locally is:
111+
- Your chosen shortcuts (undo, command bar)
112+
- Feature toggles (vim navigation, dark mode, inbox zero, options bar, AI title editing)
113+
- Custom shortcuts configuration
114+
- Gemini API key (if provided, stored locally only)
115+
116+
### Supported Domains
117+
118+
The extension is scoped to Outlook web only:
119+
120+
- `https://outlook.live.com/*`
121+
- `https://outlook.office.com/*`
122+
- `https://outlook.office365.com/*`
123+
124+
### Installation
125+
126+
#### Loading in Chrome (Developer Mode)
127+
128+
1. Clone or download this repository
129+
2. Run `npm install` to install dependencies
130+
3. Run `npm run build` to build the extension
131+
4. Open Chrome and navigate to `chrome://extensions`
132+
5. Enable **Developer mode** (top-right toggle)
133+
6. Click **Load unpacked** and select the `dist/chrome` folder
134+
7. Open Outlook on the web in a tab and start using the shortcuts
135+
136+
#### Loading in Firefox (Temporary Add-on)
137+
138+
1. Clone or download this repository
139+
2. Run `npm install` to install dependencies
140+
3. Run `npm run build` to build the extension
141+
4. Open Firefox and navigate to `about:debugging#/runtime/this-firefox`
142+
5. Click **Load Temporary Add-on…**
143+
6. Select the `manifest.json` file in the `dist/firefox` folder
144+
7. Open Outlook on the web and start using the shortcuts
145+
146+
#### Building for Distribution
147+
148+
Run `npm run package` to create distribution-ready zip files:
149+
150+
- `dist/zero-for-outlook-chrome.zip`
151+
- `dist/zero-for-outlook-firefox.zip`
152+
153+
### Project Structure
154+
155+
```text
156+
zero-for-outlook/
157+
├── src/
158+
│ ├── background/
159+
│ │ └── index.js # Background script (handles API calls, options page opening)
160+
│ ├── contentScript/
161+
│ │ ├── core/ # Core functionality
162+
│ │ │ ├── browserApi.js
163+
│ │ │ ├── dom.js
164+
│ │ │ ├── initialization.js
165+
│ │ │ ├── keyboardHandler.js
166+
│ │ │ ├── messageList.js
167+
│ │ │ ├── settings.js
168+
│ │ │ └── shortcuts.js
169+
│ │ ├── features/ # Feature modules
170+
│ │ │ ├── commandBar.js # Command bar overlay
171+
│ │ │ ├── darkMode.js # Dark theme management
172+
│ │ │ ├── elementPicker.js # Custom shortcut element picker
173+
│ │ │ ├── inboxZero.js # Inbox zero celebration
174+
│ │ │ ├── navigation.js # Navigation helpers
175+
│ │ │ ├── optionsBar.js # Outlook options bar toggle
176+
│ │ │ ├── snooze.js # Snooze overlay
177+
│ │ │ ├── summary.js # Email summarization overlay
178+
│ │ │ ├── undo.js # Undo archive
179+
│ │ │ └── vimMode.js # Vim-style navigation
180+
│ │ ├── styles/ # CSS for overlays
181+
│ │ │ ├── commandBar.css
182+
│ │ │ ├── elementPicker.css
183+
│ │ │ ├── llmEditing.css
184+
│ │ │ └── summary.css
185+
│ │ └── index.js # Content script entry point
186+
│ ├── options/ # Options page
187+
│ │ ├── index.html
188+
│ │ ├── main.js
189+
│ │ └── style.css
190+
│ ├── assets/
191+
│ │ └── icons/ # Extension icons
192+
│ └── manifest.json # Base manifest (transformed for Chrome/Firefox)
193+
├── scripts/
194+
│ ├── build.js # Build script (transforms manifest, copies files)
195+
│ └── package.js # Packaging script (creates zip files)
196+
├── dist/ # Build output
197+
│ ├── chrome/ # Chrome extension (Manifest V3)
198+
│ ├── firefox/ # Firefox extension (Manifest V2)
199+
│ └── *.zip # Distribution packages
200+
├── vite.config.mts # Vite configuration
201+
└── package.json
202+
```
203+
204+
### Development
205+
206+
- **Build**: `npm run build` - Builds the content script with Vite and copies files to `dist/chrome/` and `dist/firefox/`
207+
- **Package**: `npm run package` - Builds and creates zip files for distribution
208+
209+
The project uses:
210+
211+
- **Vite** for building the content script (bundles ES modules into a single IIFE)
212+
- **Manifest V3** for Chrome
213+
- **Manifest V2** for Firefox (required for Firefox compatibility)
214+
- **Modular architecture** with feature-based modules
215+
216+
### Customizing / Extending
217+
218+
To add more shortcuts or features:
219+
220+
1. **Add a new feature module** in `src/contentScript/features/`
221+
2. **Register it in `initialization.js`** to load and wire it up
222+
3. **Add commands to the command bar** in `commandBar.js` if applicable
223+
4. **Add options UI** in `src/options/` if configuration is needed
224+
5. **Update settings** in `src/contentScript/core/settings.js` if new settings are needed
225+
226+
### Automated Versioning
90227

91228
This repository uses GitHub Actions to automatically manage version tags.
92229

93230
**How it works:**
94231

95-
- **Triggers on Push**: Runs every time you push code to `main`.
96-
- **Calculates Version**: It looks at your previous tags. If the last tag was `v1.0.0`, it automatically bumps it to `v1.0.1` (a "patch" update).
97-
- **Tags & Pushes**: It creates the new tag in the repo automatically.
232+
- **Triggers on Push**: Runs every time you push code to `main`
233+
- **Calculates Version**: It looks at your previous tags. If the last tag was `v1.0.0`, it automatically bumps it to `v1.0.1` (a "patch" update)
234+
- **Tags & Pushes**: It creates the new tag in the repo automatically
98235

99236
You can force a larger version jump by including specific words in your commit message:
100237

@@ -103,7 +240,7 @@ You can force a larger version jump by including specific words in your commit m
103240

104241
---
105242

106-
# ToDo
243+
## ToDo
107244

108245
[Current ToDo List](https://docmost.lukeslabs.xyz/share/19xhhfhgcp/p/to-do-lzhwFvot9q)
109246

‎src/manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "Zero for Outlook",
33
"description": "Zero for Outlook adds configurable keyboard shortcuts and extends functionality of Outlook on the web.",
4-
"version": "0.5.7",
4+
"version": "0.5.8",
55
"permissions": [
66
"storage"
77
],

‎src/options/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -308,7 +308,7 @@ <h2>About this extension</h2>
308308
</section>
309309

310310
<footer class="oz-footer">
311-
<span>Version 0.5.7</span>
311+
<span>Version 0.5.8</span>
312312
<span>
313313
Copyright (C) 2025 Luke Colvin · Zero for Outlook
314314
<a

0 commit comments

Comments
 (0)