From 3204e143e4a315f8bc67d1d17c1f7efc78bfc734 Mon Sep 17 00:00:00 2001 From: P T Weir Date: Tue, 16 Jul 2024 15:45:21 +0100 Subject: [PATCH] adds docs for theming (#66) Aligns with https://github.com/atuinsh/atuin/pull/2236 to explain the usage of themes. TODO: Markdown needs to be checked, but here for feedback initially. More information is available at that PR. --- astro.config.mjs | 1 + src/content/docs/configuration/config.mdx | 45 +++++++++ src/content/docs/guide/theming.mdx | 111 ++++++++++++++++++++++ 3 files changed, 157 insertions(+) create mode 100644 src/content/docs/guide/theming.mdx diff --git a/astro.config.mjs b/astro.config.mjs index 290a0b3..3719039 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -48,6 +48,7 @@ export default defineConfig({ { label: 'Import existing history', link: '/guide/import' }, { label: 'Basic usage', link: '/guide/basic-usage' }, { label: 'Syncing dotfiles', link: '/guide/dotfiles' }, + { label: 'Theming', link: '/guide/theming' }, ], }, { diff --git a/src/content/docs/configuration/config.mdx b/src/content/docs/configuration/config.mdx index 5128dbd..ffb9ffb 100644 --- a/src/content/docs/configuration/config.mdx +++ b/src/content/docs/configuration/config.mdx @@ -623,3 +623,48 @@ The port to use for client -> daemon communication. Only used on non-unix system ```toml tcp_port = 8889 ``` + +## theme +Atuin version: >= 18.4 + +The theme to use for showing the terminal interface. + +```toml +[theme] +name = "" +debug = false +max_depth = 10 +``` + +### `name` +Default: `""` + +A theme name that must be present as a built-in (an empty string for the default, +`autumn` or `marine`), or found in the themes directory, with the suffix `.toml`. +By default this is `~/.config/atuin/themes/` but can be overridden with the +`ATUIN_THEME_DIR` environment variable. + +```toml +name = "my-theme" +``` + +### `debug` +Default: `false` + +Output information about why a theme will not load. Independent from other log +levels as it can cause data from the theme file to be printed unfiltered to the +terminal. + +```toml +debug = false +``` + +### `max_depth` +Default: 10 + +Number of levels of "parenthood" that will be traversed for a theme. This should not +need to be added in or changed in normal usage. + +```toml +max_depth = 10 +``` diff --git a/src/content/docs/guide/theming.mdx b/src/content/docs/guide/theming.mdx new file mode 100644 index 0000000..bb534f3 --- /dev/null +++ b/src/content/docs/guide/theming.mdx @@ -0,0 +1,111 @@ +--- +title: Theming +--- + +For terminal interface customization, Atuin supports user and built-in color themes. + +Atuin ships with only a couple of built-in alternative themes, but more can be added via TOML files. + +# Required config + +The following is required in your config file (`~/.config/atuin/config.toml`) + +``` +[theme] +name = "THEMENAME" +``` + +Where `THEMENAME` is a known theme. The following themes are available out-of-the-box: + +* default theme (can be explicitly referenced with an empty name `""`) +* `autumn` theme +* `marine` theme + +These are present to ensure users and developers can try out theming, but in general, you +will need to download themes or make your own. + +If you are writing your own themes, you can add the following line to get additional output: + +``` +debug = true +``` + +to the same config block. This will print out any color names that cannot be parsed from +the requested theme. + +A final optional setting is available: + +``` +max_depth: 10 +``` + +which sets the maximum levels of theme parents to traverse. This should not need to be +explicitly added in normal use. + +# Usage + +## Theme structure + +Themes are maps from *Meanings*, describing the developer's intentions, +to (at present) colors. In future, this may be expanded to allow richer style support. + +*Meanings* are from an enum with the following values: + +* `AlertInfo`: alerting the user at an INFO level +* `AlertWarn`: alerting the user at a WARN level +* `AlertError`: alerting the user at an ERROR level +* `Annotation`: less-critical, supporting text +* `Base`: default foreground color +* `Guidance`: instructing the user as help or context +* `Important`: drawing the user's attention to information +* `Title`: titling a section or view + +These may expand over time as they are added to Atuin's codebase, but Atuin +should have fallbacks added for any new *Meanings* so that, whether themes limit to +the present list or take advantage of new *Meanings* in future, they should +keep working sensibly. + +**Note for Atuin contributors**: please do identify and, where appropriate during your own +PRs, extend the Meanings enum if needed (along with a fallback Meaning!). + +## Theme creation + +When a theme name is read but not yet loaded, Atuin will look for it in the folder +`~/.config/atuin/themes/` unless overridden by the `ATUIN_THEME_DIR` environment +variable. It will attempt to open a file of name `THEMENAME.toml` and read it as a +map from *Meanings* to colors. + +Colors may be specified either as names from the [palette](https://ogeon.github.io/docs/palette/master/palette/named/index.html) +crate in lowercase, or as six-character hex codes, prefixed with `#`. For example, +the following are valid color names: + +* `#ff0088` +* `teal` +* `powderblue` + +A theme file, say `my-theme.toml` can then be built up, such as: + +```toml +[theme] +name = "my-theme" +parent = "autumn" + +[colors] +AlertInto = "green" +Guidance = "#888844" + +``` + +where not all of the *Meanings* need to be explicitly defined. If they are absent, +then the color will be chosen from the parent theme, if one is defined, or if that +key is missing in the `theme` block, from the default theme. + +This theme file should be moved to `~/.config/atuin/themes/my-theme.toml` and the +following added to `~/.config/atuin/config.toml`: + +``` +[theme] +name = "my-theme" +``` + +When you next run Atuin, your theme should be applied.