Detailed changes
@@ -105,7 +105,7 @@ jobs:
env:
CLICOLOR_FORCE: "1"
run: |
- mkdir -p docs/docs/assets/
+ mkdir -p docs/docs/assets/features/
for tape in screenshots/*.tape; do
[ "$tape" = "screenshots/common.tape" ] && continue
name=$(basename "$tape" .tape)
@@ -113,9 +113,9 @@ jobs:
TERM=xterm-256color vhs "$tape" || echo "Warning: $name failed"
done
# Move generated screenshots to public assets, clean up intermediate gifs
- mv screenshots/*.png docs/docs/assets/ 2>/dev/null || true
+ mv screenshots/*.png docs/docs/assets/features/ 2>/dev/null || true
rm -f screenshots/*.gif 2>/dev/null || true
- ls -la docs/docs/assets/
+ ls -la docs/docs/assets/features/
- name: Create Pull Request
uses: peter-evans/create-pull-request@v8
@@ -138,4 +138,4 @@ jobs:
- `drafts.png` - Draft management view
branch: "update-screenshots"
base: "master"
- add-paths: docs/docs/assets/
+ add-paths: docs/docs/assets/features/
@@ -9,16 +9,16 @@ generate_gif:
mv demo.gif public/assets/demo.gif
generate_screenshots:
- @mkdir -p docs/docs/assets/
+ @mkdir -p docs/docs/assets/features/
@for tape in screenshots/*.tape; do \
[ "$$(basename $$tape)" = "common.tape" ] && continue; \
name=$$(basename "$$tape" .tape); \
echo "==> Generating screenshot: $$name"; \
vhs "$$tape" || echo "Warning: $$name failed"; \
done
- @mv screenshots/*.png docs/docs/assets/ 2>/dev/null || true
+ @mv screenshots/*.png docs/docs/assets/features/ 2>/dev/null || true
@rm -f screenshots/*.gif 2>/dev/null || true
- @echo "Screenshots saved to public/assets/screenshots/"
+ @echo "Screenshots saved to docs/docs/assets/features/"
build:
go build -o $(BUILD_DIR)/$(BINARY_NAME) .
@@ -1,3 +1,8 @@
+---
+title: Configuration
+sidebar_position: 5
+---
+
# Configuration
Configuration is stored in `~/.config/matcha/config.json`.
@@ -1,6 +1,6 @@
# Composing Emails
- 
+ 
Matcha provides a clean, intuitive interface for writing emails.
@@ -1,6 +1,6 @@
# Draft Management
-
+
Manage your unfinished emails with ease.
@@ -1,6 +1,6 @@
# Email Management
-
+
Matcha provides comprehensive tools for managing your emails directly from the terminal.
@@ -16,6 +16,7 @@ Matcha provides comprehensive tools for managing your emails directly from the t
## Rich Email Viewing
Matcha supports rendering various email formats:
+
- HTML email rendering with proper formatting.
- Markdown support for plain-text emails.
- Styled headers and body text.
@@ -8,17 +8,17 @@ Go to **Settings > Theme** to browse available themes. A live preview panel on t
Your selection is saved to `config.json` and persists across sessions.
-
+
## Built-in Themes
-| Theme | Description |
-|-------|-------------|
-| **Matcha** | The default green theme |
-| **Rose** | Soft pink and rose accents |
-| **Lavender** | Purple and violet tones |
-| **Ocean** | Cool blue palette |
-| **Peach** | Warm orange and peach tones |
+| Theme | Description |
+| -------------------- | ----------------------------------------------------------------------- |
+| **Matcha** | The default green theme |
+| **Rose** | Soft pink and rose accents |
+| **Lavender** | Purple and violet tones |
+| **Ocean** | Cool blue palette |
+| **Peach** | Warm orange and peach tones |
| **Catppuccin Mocha** | Based on the popular [Catppuccin](https://catppuccin.com/) color scheme |
## Custom Themes
@@ -50,20 +50,20 @@ Create a file like `~/.config/matcha/themes/dracula.json`:
### Color Properties
-| Property | Used For |
-|----------|----------|
-| `accent` | Selected items, focused elements, primary highlights |
-| `accent_dark` | Borders, title backgrounds |
-| `accent_text` | Text on accent-colored backgrounds |
-| `secondary` | Help text, blurred/unfocused elements |
-| `subtle_text` | List headers, hints |
-| `muted_text` | Dates, timestamps |
-| `dim_text` | Sender names, secondary info |
-| `danger` | Delete confirmations, errors |
-| `warning` | Update notifications |
-| `tip` | Contextual tips |
-| `link` | Hyperlinks in email content |
-| `directory` | Directory names in the file picker |
-| `contrast` | Text on accent-colored backgrounds (e.g. active folder) |
+| Property | Used For |
+| ------------- | ------------------------------------------------------- |
+| `accent` | Selected items, focused elements, primary highlights |
+| `accent_dark` | Borders, title backgrounds |
+| `accent_text` | Text on accent-colored backgrounds |
+| `secondary` | Help text, blurred/unfocused elements |
+| `subtle_text` | List headers, hints |
+| `muted_text` | Dates, timestamps |
+| `dim_text` | Sender names, secondary info |
+| `danger` | Delete confirmations, errors |
+| `warning` | Update notifications |
+| `tip` | Contextual tips |
+| `link` | Hyperlinks in email content |
+| `directory` | Directory names in the file picker |
+| `contrast` | Text on accent-colored backgrounds (e.g. active folder) |
Colors can be specified as hex values (`#BD93F9`) or ANSI 256-color codes (`42`).
@@ -0,0 +1,8 @@
+{
+ "label": "Features",
+ "position": 6,
+ "link": {
+ "type": "generated-index",
+ "title": "Features"
+ }
+}
@@ -3,13 +3,14 @@ slug: /
title: Matcha Documentation
description: A modern, beautiful, and feature-rich email client for the terminal.
hide_table_of_contents: true
+sidebar_position: 1
---
# 🍵 Welcome to Matcha
**Matcha** is a modern, beautiful, and feature-rich email client for the terminal, designed for speed and efficiency.
-
+
## Getting Started
@@ -32,6 +33,7 @@ Matcha is packed with features to make email management in the terminal a breeze
- [**Advanced**](./Features/ADVANCED.md) - Automatic updates, smart image rendering, and performance optimization.
### Image & Hyperlink Support
+
- [Image Protocol Compatibility](./Features/Images.md)
- [Hyperlink Compatibility](./Features/Hyperlinks.md)
@@ -1,3 +1,8 @@
+---
+title: Installation Guide
+sidebar_position: 2
+---
+
# Installation Guide
Welcome to the installation guide for Matcha.
@@ -20,7 +25,7 @@ matcha
```
> [!WARNING]
-> If you have the [*"other"* Matcha](https://github.com/piqoni/matcha) already installed, you will have to rename the executable to avoid conflicts.
+> If you have the [_"other"_ Matcha](https://github.com/piqoni/matcha) already installed, you will have to rename the executable to avoid conflicts.
### Manual Binary Download
@@ -0,0 +1,8 @@
+{
+ "label": "Setup Guides",
+ "position": 4,
+ "link": {
+ "type": "generated-index",
+ "title": "Setup Guides"
+ }
+}
@@ -0,0 +1,54 @@
+---
+title: Gmail
+sidebar_position: 1
+---
+
+# Gmail setup
+
+Matcha requires using app passwords to access your gmail account. App Passwords are available only after 2-Step Verification is turned on.
+
+## 1. Open Google account security settings
+
+1. Go to [https://myaccount.google.com](https://myaccount.google.com).
+2. In the left menu, click **Security**.
+
+## 2. Enable 2-Step Verification (if not enabled)
+
+1. In **How you sign in to Google**, click **2-Step Verification**.
+2. Follow the setup flow (phone prompt, SMS, authenticator app, or security key).
+
+## 3. Create an App Password
+
+1. Go to [https://myaccount.google.com/u/2/apppasswords](https://myaccount.google.com/u/2/apppasswords).
+2. Sign in again if prompted.
+3. Choose a name for your app password (e.g., "Matcha").
+4. Click **Generate**.
+5. Copy the 16-character app password shown by Google.
+
+> **⚠️ Important:** Treat this app password as you would your primary password. Never share it, or expose it publicly. This credential grants full access to your Gmail account. The app password sits locally in your device and is never shared with us.
+
+
+
+## 4. Open account setup in Matcha
+
+From Matcha, open settings and choose to add a new account.
+
+## 5. Enter Gmail credentials in Matcha
+
+In Matcha account setup:
+
+- Provider: gmail
+- Display name: The name that will appear on the emails you send
+- Username: Your Gmail address
+- Email Address: The Gmail address used to fetch messages from(most likely the same as the Username)
+- Password: the generated 16-character app password (not your normal Google password)
+
+
+
+## Troubleshooting
+
+| Issue | Solution |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **Invalid credentials** | Verify you're using the 16-character app password, not your regular Google account password. |
+| **"App passwords" option missing** | Confirm 2-Step Verification is enabled in your account settings. Some organizations restrict app passwords via security policies. |
+| **Connection still fails** | In Google Account, revoke the current app password and generate a new one. Then update your credentials in Matcha. |
@@ -1,3 +1,8 @@
+---
+title: Usage
+sidebar_position: 3
+---
+
# Usage
## First Launch
@@ -11,12 +16,14 @@ On first launch, Matcha will prompt you to configure an email account. You'll ne
## Keyboard Shortcuts
### Main Menu
+
- `↑/↓` or `j/k` - Navigate menu items
- `Enter` - Select option
- `Esc` - Go back / Exit
- `Ctrl+C` - Quit application
### Inbox View
+
- `↑/↓` or `j/k` - Navigate emails
- `←/→` or `h/l` - Switch between account tabs
- `Enter` - Open selected email
@@ -27,6 +34,7 @@ On first launch, Matcha will prompt you to configure an email account. You'll ne
- `Esc` - Back to main menu
### Email View
+
- `↑/↓` or `j/k` - Scroll email content
- `r` - Reply to email
- `d` - Delete email
@@ -36,11 +44,13 @@ On first launch, Matcha will prompt you to configure an email account. You'll ne
- `i` - Toggle images
### Attachment View (when focused)
+
- `↑/↓` or `j/k` - Navigate attachments
- `Enter` - Download and open attachment
- `Tab` or `Esc` - Back to email body
### Composer
+
- `Tab` / `Shift+Tab` - Navigate fields
- `Enter` -
- On "From" field: Select account (if multiple)
@@ -58,6 +68,7 @@ matcha update
```
This command will:
+
1. Check for the latest release on GitHub
2. Detect your installation method (Homebrew, Snap, or binary)
3. Update using the appropriate method