Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ serde_json = "1.0.154"
tempfile = "3.27.0"
toml = "1.2.0"
tui-input = { version = "0.15.5", default-features = false }
umbra = "0.6.0"

[dev-dependencies]
insta = "1.49.0"
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,8 @@ In Explore / Compare:

See [Explore & Compare](https://lusingander.github.io/asinus/features/explore-compare.html) for previews and [Keybindings](https://lusingander.github.io/asinus/reference/keybindings.html) for all controls.

To customize UI colors and text styles, see [Configuration](https://lusingander.github.io/asinus/reference/configuration.html).

## License

Asinus is distributed under the [MIT License](./LICENSE).
Expand Down
147 changes: 147 additions & 0 deletions config.json.schema
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Asinus Configuration Schema",
"description": "Schema for the Asinus TOML configuration file.",
"type": "object",
"properties": {
"ui": { "$ref": "#/definitions/uiSettings" }
},
"additionalProperties": false,
"definitions": {
"uiSettings": {
"type": "object",
"properties": {
"style": { "$ref": "#/definitions/uiStyles" }
},
"additionalProperties": false
},
"uiStyles": {
"description": "Styles for the application UI. Omitted colors use the role's built-in color when available and otherwise inherit the base color.",
"type": "object",
"properties": {
"base": { "$ref": "#/definitions/baseStyle" },
"heading": {
"description": "View and panel headings.",
"allOf": [{ "$ref": "#/definitions/style" }],
"default": { "modifiers": ["bold"] }
},
"focus": {
"description": "The active panel or input control.",
"allOf": [{ "$ref": "#/definitions/style" }],
"default": { "fg": "cyan", "modifiers": ["bold"] }
},
"selection": {
"description": "Selected rows and menu items. Set modifiers to an empty array to disable the default reverse video.",
"allOf": [{ "$ref": "#/definitions/style" }],
"default": { "modifiers": ["reverse"] }
},
"key": {
"description": "Shortcut keys in footers and Help. Help uses bold by default.",
"allOf": [{ "$ref": "#/definitions/style" }],
"default": { "fg": "cyan" }
},
"muted": {
"description": "Descriptions beside shortcut keys in footers.",
"allOf": [{ "$ref": "#/definitions/style" }]
},
"condition_key": {
"description": "Search condition keys such as type:.",
"allOf": [{ "$ref": "#/definitions/style" }],
"default": { "fg": "green" }
},
"search_match": {
"description": "Matching text in theme names.",
"allOf": [{ "$ref": "#/definitions/style" }],
"default": { "fg": "yellow", "modifiers": ["bold"] }
},
"comparison_diff": {
"description": "Color comparison difference labels.",
"allOf": [{ "$ref": "#/definitions/style" }],
"default": { "fg": "yellow" }
},
"notice": {
"description": "Informational notices.",
"allOf": [{ "$ref": "#/definitions/style" }],
"default": { "fg": "blue" }
},
"success": {
"description": "Success notices.",
"allOf": [{ "$ref": "#/definitions/style" }],
"default": { "fg": "green" }
},
"warning": {
"description": "Warning notices.",
"allOf": [{ "$ref": "#/definitions/style" }],
"default": { "fg": "yellow" }
},
"error": {
"description": "Error notices and search input errors. Search input errors use bold by default.",
"allOf": [{ "$ref": "#/definitions/style" }],
"default": { "fg": "red" }
}
},
"additionalProperties": false
},
"baseStyle": {
"description": "Base foreground and background colors for the application UI.",
"type": "object",
"properties": {
"fg": {
"allOf": [{ "$ref": "#/definitions/color" }],
"default": "default"
},
"bg": {
"allOf": [{ "$ref": "#/definitions/color" }],
"default": "default"
}
},
"additionalProperties": false
},
"style": {
"type": "object",
"properties": {
"fg": { "$ref": "#/definitions/color" },
"bg": { "$ref": "#/definitions/color" },
"modifiers": {
"description": "Text attributes that replace the default attributes for this role. An empty array clears them. Omit this field to use the default attributes.",
"type": "array",
"items": {
"enum": ["bold", "dim", "underline", "reverse"]
}
}
},
"additionalProperties": false
},
"color": {
"description": "An ANSI palette color name, an RGB color in #RRGGBB form, or default for the terminal's default color.",
"type": "string",
"anyOf": [
{
"enum": [
"default",
"black",
"red",
"green",
"yellow",
"blue",
"magenta",
"cyan",
"white",
"bright_black",
"bright_red",
"bright_green",
"bright_yellow",
"bright_blue",
"bright_magenta",
"bright_cyan",
"bright_white"
]
},
{
"pattern": "^#[0-9A-Fa-f]{6}$",
"maxLength": 7
}
]
}
}
}
1 change: 1 addition & 0 deletions docs/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,6 @@
# Reference

- [Keybindings](reference/keybindings.md)
- [Configuration](reference/configuration.md)
- [Data Files](reference/data-files.md)
- [Compatibility](reference/compatibility.md)
2 changes: 1 addition & 1 deletion docs/src/reference/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Asinus targets macOS and Linux. Windows is not currently supported.

Use a terminal with True Color (24-bit RGB) support and at least **60 columns × 22 rows**. Larger windows give previews more room. Some panels fill the screen at smaller sizes, and preview content may be clipped.

The surrounding UI uses your terminal's colors; previews use the selected theme's RGB colors. Text attributes such as bold and dim depend on terminal settings.
The surrounding UI uses your terminal's colors by default. Preview samples use the selected theme's RGB colors. Text attributes such as bold and dim depend on terminal settings. To customize the UI, see [Configuration](configuration.md).

## Clipboard

Expand Down
62 changes: 62 additions & 0 deletions docs/src/reference/configuration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Configuration

Use `config.toml` to customize the Asinus UI.

## Configuration File Location

Asinus selects the configuration file in this order.

1. The path set in `ASINUS_CONFIG_FILE`.
2. `$XDG_CONFIG_HOME/asinus/config.toml` if `XDG_CONFIG_HOME` is nonempty.
3. `$HOME/.config/asinus/config.toml`.

Asinus reads only the selected file. Relative paths are resolved from the current working directory. If the selected default file is missing, Asinus uses its built-in settings.

An empty `ASINUS_CONFIG_FILE`, a missing file specified by that variable, or an unreadable or invalid configuration file prevents startup. Unknown settings are reported as errors.

## Create a Configuration

Save the following example as `config.toml` in your current directory. It sets the colors of selected items and turns off reverse video.

```toml
[ui.style.selection]
fg = "#1e1e2e"
bg = "#89b4fa"
modifiers = []
```

Run Asinus with this file.

```sh
ASINUS_CONFIG_FILE=./config.toml asinus
```

All settings are optional. Add only the values you want to change.

## UI Style

`[ui.style]` controls the application UI. Preview samples and color swatches use the colors of the theme being inspected.

Each setting below is a table under `[ui.style]`. Use `fg` for the foreground color and `bg` for the background color. When omitted, `bg` inherits from `base`, and `fg` uses the listed color or inherits from `base`.

| Setting | Default | Use |
| --- | --- | --- |
| `base` | `"default"` for both colors | Main text and background |
| `heading` | Bold | Screen and panel headings |
| `focus` | `"cyan"`, bold | Active panels and controls |
| `selection` | Reverse video | Selected rows and menu items |
| `key` | `"cyan"`, bold in Help | Shortcut keys in Help and footers |
| `muted` | Base colors | Descriptions beside shortcut keys in footers |
| `condition_key` | `"green"` | Keys in search conditions |
| `search_match` | `"yellow"`, bold | Matching text in theme names |
| `comparison_diff` | `"yellow"` | Difference labels in Color details |
| `notice` | `"blue"` | Informational notices |
| `success` | `"green"` | Success notices |
| `warning` | `"yellow"` | Warning notices |
| `error` | `"red"`, bold for search input errors | Error notices and search input errors |

Color values are strings. Use `"default"` for the terminal's default color or `"#RRGGBB"` for an RGB color. ANSI color names are `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, and `white`, plus their `bright_` forms such as `bright_cyan`.

Styles other than `base` also accept a `modifiers` array with `"bold"`, `"dim"`, `"underline"`, and `"reverse"`. An explicit array replaces the default attributes, and `[]` clears them. Omit the array to keep the default attributes.

For editor validation, see the [configuration schema](https://github.com/lusingander/asinus/blob/master/config.json.schema).
2 changes: 1 addition & 1 deletion docs/src/reference/data-files.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Data Files

Asinus manages two TOML files:
Asinus saves application data in two TOML files. For the settings file you edit, see [Configuration](configuration.md).

| File | Contents | Path override |
| --- | --- | --- |
Expand Down
Loading
Loading