From 2f7c018788316ddea6ad0d6225e5c102d9fb9e46 Mon Sep 17 00:00:00 2001 From: Aly Raffauf Date: Thu, 22 Jan 2026 00:01:57 -0500 Subject: [PATCH] add Configuration doc --- README.md | 102 ++--------------------------------------- docs/Configuration.md | 103 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+), 99 deletions(-) create mode 100644 docs/Configuration.md diff --git a/README.md b/README.md index 34a7224..7643b5b 100644 --- a/README.md +++ b/README.md @@ -125,106 +125,10 @@ switchyard "https://example.com" - `Ctrl+Q` - Quit -## Configuration - -Config file location: `~/.config/switchyard/config.toml` or `~/.var/app/io.github.alyraffauf.Switchyard/config/switchyard/config.toml` for Flatpak. - -```toml -prompt_on_click = true -favorite_browser = "" -check_default_browser = true - -# Simple rule with a single condition -[[rules]] -name = "Work GitHub" -browser = "firefox.desktop" - -[[rules.conditions]] -type = "domain" -pattern = "github.com" - -# Multi-condition rule with AND logic -[[rules]] -name = "Google Docs" -logic = "all" # all conditions must match -browser = "google-chrome.desktop" - -[[rules.conditions]] -type = "domain" -pattern = "docs.google.com" - -[[rules.conditions]] -type = "keyword" -pattern = "edit" - -# Multi-condition rule with OR logic -[[rules]] -name = "Video Sites" -logic = "any" # any condition can match -browser = "brave-browser.desktop" - -[[rules.conditions]] -type = "domain" -pattern = "youtube.com" - -[[rules.conditions]] -type = "domain" -pattern = "vimeo.com" - -[[rules.conditions]] -type = "domain" -pattern = "twitch.tv" - -# Rule with always ask -[[rules]] -name = "Shopping Sites" -always_ask = true - -[[rules.conditions]] -type = "keyword" -pattern = "amazon" -``` - -### Rule Options - -| Field | Description | -| ------------ | --------------------------------------------------------------------- | -| `name` | Optional friendly name displayed in the UI | -| `conditions` | Array of conditions to match (see below) | -| `logic` | How to combine conditions: `all` (AND) or `any` (OR). Default: `all` | -| `browser` | Desktop file ID of the target browser | -| `always_ask` | If true, show browser picker instead of auto-opening (default: false) | - -### Condition Options - -| Field | Description | -| --------- | --------------------------------------------------- | -| `type` | Match type: `domain`, `keyword`, `glob`, or `regex` | -| `pattern` | The pattern to match against | - -### Condition Types - -| Type | Description | Example | -| --------- | ------------------------------------------- | ---------------------------------- | -| `domain` | Exact Domain - matches specific hostname | `github.com` | -| `keyword` | URL Contains - matches if URL contains text | `youtube.com/watch` | -| `glob` | Wildcard - pattern with \* wildcards | `*.github.com` | -| `regex` | Regex - regular expression matching | `^https://.*\.example\.(com\|org)` | - -### Logic Modes - -- **`all`** (AND logic): All conditions in the rule must match for the rule to apply -- **`any`** (OR logic): Any single condition matching will trigger the rule - -Use `all` for precise targeting (e.g., "docs.google.com AND contains 'edit'") and `any` for broad matching (e.g., "youtube.com OR vimeo.com OR twitch.tv"). - -### Settings +## Documentation -| Setting | Description | -| ----------------------- | ---------------------------------------------------------------------------------------------------- | -| `prompt_on_click` | Show picker when no rule matches (default: true) | -| `favorite_browser` | Favorite browser that always appears first in picker and is used as fallback when picker is disabled | -| `check_default_browser` | Prompt to set Switchyard as system default browser on startup (default: true) | +- [Configuration](docs/Configuration.md) - Config file format, rules, and settings. +- [URI Scheme](docs/URI%20Scheme.md) - Custom `switchyard://` URLs for specifying browser preferences. ## Development diff --git a/docs/Configuration.md b/docs/Configuration.md new file mode 100644 index 0000000..48cfb29 --- /dev/null +++ b/docs/Configuration.md @@ -0,0 +1,103 @@ +# Configuration + +Switchyard can be configured through its settings UI or by editing the config file directly. + +## Config File Location + +- Standard: `~/.config/switchyard/config.toml` +- Flatpak: `~/.var/app/io.github.alyraffauf.Switchyard/config/switchyard/config.toml` + +## Example + +```toml +prompt_on_click = true +favorite_browser = "" +check_default_browser = true + +# Simple rule with a single condition +[[rules]] +name = "Work GitHub" +browser = "firefox.desktop" + +[[rules.conditions]] +type = "domain" +pattern = "github.com" + +# Multi-condition rule with AND logic +[[rules]] +name = "Google Docs" +logic = "all" # all conditions must match +browser = "google-chrome.desktop" + +[[rules.conditions]] +type = "domain" +pattern = "docs.google.com" + +[[rules.conditions]] +type = "keyword" +pattern = "edit" + +# Multi-condition rule with OR logic +[[rules]] +name = "Video Sites" +logic = "any" # any condition can match +browser = "brave-browser.desktop" + +[[rules.conditions]] +type = "domain" +pattern = "youtube.com" + +[[rules.conditions]] +type = "domain" +pattern = "vimeo.com" + +[[rules.conditions]] +type = "domain" +pattern = "twitch.tv" + +# Rule with always ask +[[rules]] +name = "Shopping Sites" +always_ask = true + +[[rules.conditions]] +type = "keyword" +pattern = "amazon" +``` + +## Settings + +- **prompt_on_click**: Show picker when no rule matches (default: true). +- **favorite_browser**: Favorite browser that always appears first in picker and is used as fallback when picker is disabled. +- **check_default_browser**: Prompt to set Switchyard as system default browser on startup (default: true). + +## Rules + +Rules define how URLs are routed to browsers. Each rule has conditions that determine when it matches. + +- **name**: Optional friendly name displayed in the UI. +- **conditions**: Array of conditions to match (see below). +- **logic**: How to combine conditions: `all` (AND) or `any` (OR). Default: `all`. +- **browser**: [Desktop file ID](https://specifications.freedesktop.org/desktop-entry-spec/latest/) of the target browser (e.g. `firefox.desktop`, `com.google.Chrome.desktop`). +- **always_ask**: If true, show browser picker instead of auto-opening (default: false). + +## Conditions + +Each condition specifies a pattern to match against the URL. + +- **type**: Match type (see below). +- **pattern**: The pattern to match against. + +## Condition Types + +- **domain**: Exact domain match (e.g. `github.com`). +- **keyword**: URL contains text (e.g. `youtube.com/watch`). +- **glob**: Wildcard pattern with `*` (e.g. `*.github.com`). +- **regex**: Regular expression (e.g. `^https://.*\.example\.(com|org)`). + +## Logic Modes + +- **all** (AND): All conditions must match for the rule to apply. +- **any** (OR): Any single condition matching triggers the rule. + +Use `all` for precise targeting (e.g., "docs.google.com AND contains 'edit'") and `any` for broad matching (e.g., "youtube.com OR vimeo.com OR twitch.tv"). -- 2.51.2