From 29e54c8263d05b6d61db2a5272c320baeee67624 Mon Sep 17 00:00:00 2001 From: Evan Simkowitz Date: Mon, 11 Nov 2024 16:08:56 -0800 Subject: [PATCH] Move presets docs to own page (#1268) --- docs/docs/config.mdx | 97 -------------------------------------- docs/docs/presets.mdx | 107 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+), 97 deletions(-) create mode 100644 docs/docs/presets.mdx diff --git a/docs/docs/config.mdx b/docs/docs/config.mdx index a1ff0c0aa..89870f657 100644 --- a/docs/docs/config.mdx +++ b/docs/docs/config.mdx @@ -174,100 +174,3 @@ wsh editconfig termthemes.json | background | CSS color | | | background color (default when no color code is applied), must have alpha channel (#rrggbbaa) if you want the terminal to be transparent | | cursorAccent | CSS color | | | color for cursor | | selectionBackground | CSS color | | | background color for selected text | - -## Presets - -Presets can be used to apply multiple setting overrides to either a tab or a block. They are currently supported in two scenarios: tab backgrounds and AI models. - -You can set presets either by placing them in `~/.config/waveterm/presets.json` or by placing them in a JSON file in the `~/.config/waveterm/presets/` directory. All presets will be aggregated regardless of which file they're placed in so you can use the `presets` directory to organize them as you see fit. - -### File format - -Presets follow the following format: - -```json -{ - ... - "@": { - "display:name": "", - "display:order": "", // optional - "": "" - ... - } -} -``` - -A complete example of a preset for a tab background is the following: - -```json -{ - "bg@rainbow": { - "display:name": "Rainbow", - "display:order": 2.1, - "bg:*": true, - "bg": "linear-gradient( 226.4deg, rgba(255,26,1,1) 28.9%, rgba(254,155,1,1) 33%, rgba(255,241,0,1) 48.6%, rgba(34,218,1,1) 65.3%, rgba(0,141,254,1) 80.6%, rgba(113,63,254,1) 100.1% )", - "bg:opacity": 0.3 - } -} -``` - -A complete example of a preset for an AI model is the following: - -```json -{ - "ai@wave": { - "display:name": "Ollama - llama3.1", - "display:order": 0, - "ai:baseurl": "http://localhost:11434", - "ai:model": "llama3.1:latest" - } -} -``` - -### Preset type - -The type of the preset determines where it can be discovered in the app. Currently, the two types that will be discovered in the app are `bg` and `ai`. - -`bg` will be served in the "Backgrounds" submenu of the Tab context menu (which can be found by right-clicking on a tab). - -![screenshot showing the default options in the backgrounds submenu of the tab context menu](./img/backgrounds-menu.png) - -`ai` will be served in the models dropdown in the block header of the "Wave AI" widget. - -![screenshot showing the default options in the models dropdown in the block header of the "Wave AI" widget](./img/waveai-model-dropdown.png) - -### Available configuration keys - -The following configuration keys are available for use in presets: - -#### AI configurations: - -| Key Name | Type | Function | -| ------------- | ------ | -------------------------------------------------------------------------------- | -| ai:preset | string | the default AI preset to use | -| ai:baseurl | string | Set the AI Base Url (must be OpenAI compatible) | -| ai:apitoken | string | your AI api token | -| ai:apitype | string | defaults to "open_ai", but can also set to "azure" for special Azure AI handling | -| ai:name | string | string to display in the Wave AI block header | -| ai:model | string | model name to pass to API | -| ai:apiversion | string | for Azure AI only (when apitype is "azure", this will default to "2023-05-15") | -| ai:orgid | string | | -| ai:maxtokens | int | max tokens to pass to API | -| ai:timeoutms | int | timeout (in milliseconds) for AI calls | - -#### Background configurations: - -| Key Name | Type | Function | -| -------------------- | ------ | ----------------------------------------------------------------------------------------------- | -| bg:opacity | float | the opacity of the background | -| bg:blendmode | string | the [blend mode](https://developer.mozilla.org/en-US/docs/Web/CSS/blend-mode) of the background | -| bg:bordercolor | string | the color of the border | -| bg:activebordercolor | string | the color of the border when a block is active | - -#### Clear key - -Configs in a preset are applied in order to override the default config values, which will persist for the remainder of the tab or block's lifetime. Setting `bg:*` or `ai:*` to `"true"` will clear the values of any previously overridden Background or AI configurations, respectively, setting them back to their defaults. - -#### Unset a default value - -To unset a default value in a preset, add an override that sets it to an empty string, like `""`. diff --git a/docs/docs/presets.mdx b/docs/docs/presets.mdx new file mode 100644 index 000000000..0435c1652 --- /dev/null +++ b/docs/docs/presets.mdx @@ -0,0 +1,107 @@ +--- +sidebar_position: 3 +id: "presets" +title: "Presets" +--- + +Presets can be used to apply multiple setting overrides at once to either a tab or a block. They are currently supported in two scenarios: tab backgrounds and AI models. + +You can set presets either by placing them in `~/.config/waveterm/presets.json` or by placing them in a JSON file in the `~/.config/waveterm/presets/` directory. All presets will be aggregated regardless of which file they're placed in so you can use the `presets` directory to organize them as you see fit. + +### File format + +Presets follow the following format: + +```json +{ + ... + "@": { + "display:name": "", + "display:order": "", // optional + "": "" + ... + } +} +``` + +A complete example of a preset for a tab background is the following: + +```json +{ + "bg@rainbow": { + "display:name": "Rainbow", + "display:order": 2.1, + "bg:*": true, + "bg": "linear-gradient( 226.4deg, rgba(255,26,1,1) 28.9%, rgba(254,155,1,1) 33%, rgba(255,241,0,1) 48.6%, rgba(34,218,1,1) 65.3%, rgba(0,141,254,1) 80.6%, rgba(113,63,254,1) 100.1% )", + "bg:opacity": 0.3 + } +} +``` + +A complete example of a preset for an AI model is the following: + +```json +{ + "ai@wave": { + "display:name": "Ollama - llama3.1", + "display:order": 0, + "ai:baseurl": "http://localhost:11434", + "ai:model": "llama3.1:latest" + } +} +``` + +### Preset type + +The type of the preset determines where it can be discovered in the app. Currently, the two types that will be discovered in the app are `bg` and `ai`. + +`bg` will be served in the "Backgrounds" submenu of the Tab context menu (which can be found by right-clicking on a tab). + +![screenshot showing the default options in the backgrounds submenu of the tab context menu](./img/backgrounds-menu.png) + +`ai` will be served in the models dropdown in the block header of the "Wave AI" widget. + +![screenshot showing the default options in the models dropdown in the block header of the "Wave AI" widget](./img/waveai-model-dropdown.png) + +### Available configuration keys + +The following configuration keys are available for use in presets: + +#### Common keys + +| Key Name | Type | Function | +| ------------- | ------ | ---------------------------------------------------------------------- | +| display:name | string | the name to use when displaying the preset in a menu (required) | +| display:order | float | the order in which the preset should be displayed in a menu (optional) | + +#### AI configurations + +| Key Name | Type | Function | +| ------------- | ------ | -------------------------------------------------------------------------------- | +| ai:preset | string | the default AI preset to use | +| ai:baseurl | string | Set the AI Base Url (must be OpenAI compatible) | +| ai:apitoken | string | your AI api token | +| ai:apitype | string | defaults to "open_ai", but can also set to "azure" for special Azure AI handling | +| ai:name | string | string to display in the Wave AI block header | +| ai:model | string | model name to pass to API | +| ai:apiversion | string | for Azure AI only (when apitype is "azure", this will default to "2023-05-15") | +| ai:orgid | string | | +| ai:maxtokens | int | max tokens to pass to API | +| ai:timeoutms | int | timeout (in milliseconds) for AI calls | + +#### Background configurations + +| Key Name | Type | Function | +| -------------------- | ------ | ----------------------------------------------------------------------------------------------- | +| bg:opacity | float | the opacity of the background | +| bg:blendmode | string | the [blend mode](https://developer.mozilla.org/en-US/docs/Web/CSS/blend-mode) of the background | +| bg:bordercolor | string | the color of the border | +| bg:activebordercolor | string | the color of the border when a block is active | + +#### Clear key + +Configs in a preset are applied in order to override the default config values, which will persist for the remainder of the tab or block's lifetime. Setting `bg:*` or `ai:*` to `"true"` will clear the values of any previously overridden Background or AI configurations, respectively, setting them back to their defaults. + +#### Unset a default value + +To unset a default value in a preset, add an override that sets it to an empty string, like `""`.