From 74514be9cdb16c6ca4042c87d2c06cbd09a8e8ea Mon Sep 17 00:00:00 2001 From: Mike Donnalley Date: Thu, 16 Nov 2023 13:49:54 -0700 Subject: [PATCH 1/2] feat: document themes --- docs/themes.md | 128 ++++++++++++++++++++++++++++++++++++++++++ website/sidebars.json | 8 +-- 2 files changed, 131 insertions(+), 5 deletions(-) create mode 100644 docs/themes.md diff --git a/docs/themes.md b/docs/themes.md new file mode 100644 index 00000000..eecebef4 --- /dev/null +++ b/docs/themes.md @@ -0,0 +1,128 @@ +--- +title: Themes +--- + +oclif supports themes that users can either define for themselves or select from a variety of themes you ship with your CLI. + +By default, the theme only applies to help output but you can extend the theme for your own purposes if you want. See [Extending Themes](#extending-themes) section below. + +## themes.json + +By default oclif will read themes from `~/.config//themes.json`. + +This file takes the following shape: + +```json +{ + // the theme that oclif will use. Must correspond to one of the themes under the `themes` property + "selected": "dark" + // the list of themes that the user can choose from + "themes": { + "dark": { + "bin": "white", + "command": "cyan", + "commandSummary": "white", + "dollarSign": "white", + "flag": "white", + "flagDefaultValue": "blue", + "flagOptions": "white", + "flagRequired": "red", + "flagSeparator": "white", + "sectionDescription": "white", + "sectionHeader": "underline", + "topic": "white", + "version": "white" + }, + "light": { + "bin": "black", + "command": "cyan", + "commandSummary": "black", + "dollarSign": "black", + "flag": "black", + "flagDefaultValue": "blue", + "flagOptions": "black", + "flagRequired": "red", + "flagSeparator": "black", + "sectionDescription": "black", + "sectionHeader": "underline", + "topic": "black", + "version": "black" + } + } +} +``` + +### Supported Theme Properties + +As mentioned, the theme only applies to help output by default. The following properties can be used: + +- `alias`: the aliases under the `ALIASES` section +- `bin`: the name of your CLI's executable (e.g. `sf`, `heroku`) +- `command`: the command's name +- `commandSummary`: the command's summary +- `dollarSign`: the `$` printed before `examples` and `usage` +- `flag`: flag names and short characters +- `flagDefaultValue`: the `[default: X]` shown on flags with a default +- `flagOptions`: the valid options for a flag +- `flagRequired`: the `(required)` that shows on required flags +- `flagSeparator`: the `,` that separates the short char and long flag names (e.g. `-f, --foo`) +- `sectionDescription`: the text inside of each section (e.g. everything under `DESCRIPTION`) +- `sectionHeader`: the section header (e.g. `DESCRIPTION`) +- `topic`: the topics under the `TOPICS` section +- `version`: the `VERSION` section that shows under the root help (e.g. `sf --help`) + +The values for each of these must be one of the following: +- a hex code, e.g. `#FF0000` +- a rgb, e.g. `rgb(255,255,255)` +- a style supported by `chalk` (see https://github.com/chalk/chalk/#styles) + +Any invalid values will be ignored. + +## Shipping Themes with Your CLI + +If you'd like to ship one or more themes with your CLI you only need to do a couple of things: + +In your CLI's package.json you need to point oclif to your themes JSON file and be sure to include the file in the `files` section so that it gets included in the published package: + +```json +// package.json +"files": ["themes.json"], +"oclif": { + "themesFile": "themes.json" +} +``` + +oclif will now read themes from the configured themes files instead of the default `~/.config//themes.json`. + +## Managing Themes + +Users can manage themes in a couple of different ways. + +1. They can modify the themes file directly. If your CLI configures a `themesFile` (as described above) then they will modify that file. If not, then they would need to modify the default `~/.config//themes.json`. +2. They can install `@oclif/plugin-theme` to get a set of commands for managing themes. + +## Disabling Themes + +Themes can be disabled by using `_DISABLE_THEME` environment variable. + +## Extending Themes + +By default oclif only uses the theme for the help output but you can use the theme for other purposes if you desire. For instance maybe you'd like to log colorized `info:` logs to the user during a command: + +```typescript +import {Command, ux} from '@oclif/core' + +export default class Hello extends Command { + public async run(): Promise { + this.info('starting process!') + // do some stuff... + this.info('still making progress!') + // do some more stuff... + this.info('process complete!') + } + + public info(msg: string): void { + this.log(ux.colorize(this.config.theme?.info, 'info:'), msg) + } +} +``` diff --git a/website/sidebars.json b/website/sidebars.json index b9b8b226..4fb6c36b 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -6,10 +6,7 @@ "faqs", "generator_commands" ], - "Architecture": [ - "command_execution", - "plugin_loading" - ], + "Architecture": ["command_execution", "plugin_loading"], "API Reference": [ "commands", "args", @@ -39,7 +36,8 @@ "flexible_taxonomy", "global_flags", "single_command_cli", - "esm" + "esm", + "themes" ], "Also See": [ "examples", From fe713529a691632edf9d3919d1d439cd118f9ee9 Mon Sep 17 00:00:00 2001 From: Mike Donnalley Date: Mon, 20 Nov 2023 12:50:03 -0700 Subject: [PATCH 2/2] chore: update themes docs --- docs/themes.md | 75 ++++++++++---------------------------------------- 1 file changed, 15 insertions(+), 60 deletions(-) diff --git a/docs/themes.md b/docs/themes.md index eecebef4..61d30b56 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -6,49 +6,27 @@ oclif supports themes that users can either define for themselves or select from By default, the theme only applies to help output but you can extend the theme for your own purposes if you want. See [Extending Themes](#extending-themes) section below. -## themes.json +## theme.json -By default oclif will read themes from `~/.config//themes.json`. +By default oclif will read themes from `~/.config//theme.json`. This file takes the following shape: ```json { - // the theme that oclif will use. Must correspond to one of the themes under the `themes` property - "selected": "dark" - // the list of themes that the user can choose from - "themes": { - "dark": { - "bin": "white", - "command": "cyan", - "commandSummary": "white", - "dollarSign": "white", - "flag": "white", - "flagDefaultValue": "blue", - "flagOptions": "white", - "flagRequired": "red", - "flagSeparator": "white", - "sectionDescription": "white", - "sectionHeader": "underline", - "topic": "white", - "version": "white" - }, - "light": { - "bin": "black", - "command": "cyan", - "commandSummary": "black", - "dollarSign": "black", - "flag": "black", - "flagDefaultValue": "blue", - "flagOptions": "black", - "flagRequired": "red", - "flagSeparator": "black", - "sectionDescription": "black", - "sectionHeader": "underline", - "topic": "black", - "version": "black" - } - } + "bin": "white", + "command": "cyan", + "commandSummary": "white", + "dollarSign": "white", + "flag": "white", + "flagDefaultValue": "blue", + "flagOptions": "white", + "flagRequired": "red", + "flagSeparator": "white", + "sectionDescription": "white", + "sectionHeader": "underline", + "topic": "white", + "version": "white" } ``` @@ -78,29 +56,6 @@ The values for each of these must be one of the following: Any invalid values will be ignored. -## Shipping Themes with Your CLI - -If you'd like to ship one or more themes with your CLI you only need to do a couple of things: - -In your CLI's package.json you need to point oclif to your themes JSON file and be sure to include the file in the `files` section so that it gets included in the published package: - -```json -// package.json -"files": ["themes.json"], -"oclif": { - "themesFile": "themes.json" -} -``` - -oclif will now read themes from the configured themes files instead of the default `~/.config//themes.json`. - -## Managing Themes - -Users can manage themes in a couple of different ways. - -1. They can modify the themes file directly. If your CLI configures a `themesFile` (as described above) then they will modify that file. If not, then they would need to modify the default `~/.config//themes.json`. -2. They can install `@oclif/plugin-theme` to get a set of commands for managing themes. - ## Disabling Themes Themes can be disabled by using `_DISABLE_THEME` environment variable.