xdg-sanity/README.md

The `xdg-sanity` script is built to replace your default web browser in your
desktop/XDG settings. It intercepts http/s URIs sent to the default browser by
`xdg-open` and sends it to the appropriate application. For example, it will
send `image/jpeg` MIME type files to your image viewer.

## Installation

### Arch Linux

I maintain a package [on the
AUR](https://aur.archlinux.org/packages/xdg-sanity).

### From Source

Dependencies:
- `curl(1)`
- `handlr(1)`
- [`tomcat(1)`](https://git.tebibyte.media/emma/tomcat) (optional; enables
[extensions](#extensions))

Instructions:
Clone this repository and move the `xdg-sanity` binary wherever your operating
system stores locally-installed binaries. This is usually `/usr/local/bin/` or
`"$HOME/.local/bin/"` for your user. Make sure the installation location is in
your `$PATH`.

Create an `xdg-sanity.desktop` file, placing it where your OS stores
locally-installed `.desktop` files, which is usually
`/usr/local/share/applications` or `$XDG_DATA_HOME/applications` for your user.
Set your default web browser to that `.desktop` file using `handlr set`.

#### Extensions

Extensions are written using TOML and are stored in either
`/usr/share/xdg-sanity` when installed from a package manager,
`/usr/local/share/xdg-sanity` when installed locally, or
`$XDG_DATA_HOME/xdg-sanity` for your user.

Extension support requires the installation of the `tomcat(1)` tool, which
parses TOML for the command line.

There are two types of extensions: MIME and replace. MIME extensions are parsed
first and replace the MIME type of the content being fetched. Replace extensions
change the URI passed to the command to another.

The type of the extension depends on the file name. MIME extensions should have
a name ending in `-mime.toml` and replace extensions should have 
`-replace.toml`.

Here's what a MIME extension looks like:
```
$ cat $XDG_DATA_HOME/xdg-sanity/youtube-mime.toml
[replace]
urls = [ "youtube.com", "youtu.be" ]

[with]
mime = "video/vnd.youtube.yt"
```
and here's what a replace extension looks like:
```
$ cat $XDG_DATA_HOME/xdg-sanity/youtube-replace.toml
[replace]
urls = [ "youtube.com", "youtu.be" ]

[with] 
url = "https://piped.mint.lgbt/"
```