From cb1f48b56ae0de93acb72e48726c7d610a1d538e Mon Sep 17 00:00:00 2001 From: Jan De Dobbeleer Date: Mon, 15 Nov 2021 19:20:27 +0100 Subject: [PATCH] docs: better layout for block and segment --- docs/docs/config-block.md | 60 ++++++ docs/docs/config-example.md | 96 +++++++++ docs/docs/config-overview.md | 329 +------------------------------ docs/docs/config-segment.md | 219 ++++++++++++++++++++ docs/docs/segment-environment.md | 2 +- docs/sidebars.js | 3 + 6 files changed, 381 insertions(+), 328 deletions(-) create mode 100644 docs/docs/config-block.md create mode 100644 docs/docs/config-example.md create mode 100644 docs/docs/config-segment.md diff --git a/docs/docs/config-block.md b/docs/docs/config-block.md new file mode 100644 index 00000000..df1ee541 --- /dev/null +++ b/docs/docs/config-block.md @@ -0,0 +1,60 @@ +--- +id: config-block +title: Block +sidebar_label: Block +--- + +Let's take a closer look at what defines a block. + +```json +{ + "$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json", + ... + "blocks": [ + { + "type": "prompt", + "alignment": "left", + "segments": [ + ... + ] + } + ] +} +``` + +- type: `prompt` | `rprompt` +- newline: `boolean` +- alignment: `left` | `right` +- vertical_offset: `int` +- horizontal_offset: `int` +- segments: `array` of one or more `segments` + +### Type + +Tells the engine what to do with the block. There are three options: + +- `prompt` renders one or more segments +- `rprompt` renders one or more segments aligned to the right of the cursor. Only one `rprompt` block is permitted. +Supported on [ZSH][rprompt], Bash and Powershell. + +### Newline + +Start the block on a new line. Defaults to `false`. + +### Alignment + +Tell the engine if the block should be left or right-aligned. + +### Vertical offset + +Move the block up or down x lines. For example, `vertical_offset: 1` moves the prompt down one line, `vertical_offset: -1` +moves it up one line. + +### Horizontal offset + +Moves the segment to the left or the right to have it exactly where you want it to be. Works like `vertical_offset` +but on a horizontal level where a negative number moves the block left and a positive number right. + +### Segments + +Array of one or more segments. diff --git a/docs/docs/config-example.md b/docs/docs/config-example.md new file mode 100644 index 00000000..c180c4f4 --- /dev/null +++ b/docs/docs/config-example.md @@ -0,0 +1,96 @@ +--- +id: config-sample +title: Sample +sidebar_label: Sample +--- + +```json +{ + "final_space": true, + "blocks": [ + { + "type": "prompt", + "alignment": "right", + "vertical_offset": -1, + "segments": [ + { + "type": "time", + "style": "plain", + "foreground": "#007ACC", + "properties": { + "time_format": "15:04:05" + } + } + ] + }, + { + "type": "prompt", + "alignment": "left", + "newline": true, + "segments": [ + { + "type": "session", + "style": "diamond", + "foreground": "#ffffff", + "background": "#ffb300", + "leading_diamond": "\uE0B6", + "trailing_diamond": "\uE0B0", + "properties": { + "postfix": " " + } + }, + { + "type": "path", + "style": "powerline", + "powerline_symbol": "\uE0B0", + "foreground": "#ffffff", + "background": "#61AFEF", + "properties": { + "prefix": " \uE5FF ", + "style": "folder", + "exclude_folders": [ + "/super/secret/project" + ], + "enable_hyperlink": false + } + }, + { + "type": "git", + "style": "powerline", + "foreground": "#193549", + "foreground_templates": [ + "{{ if and (gt .Ahead 0) (gt .Behind 0) }}#ffffff{{ end }}" + ], + "background": "#2e9599", + "background_templates": [ + "{{ if or (.Working.Changed) (.Staging.Changed) }}#f36943{{ end }}", + "{{ if and (gt .Ahead 0) (gt .Behind 0) }}#a8216b{{ end }}", + "{{ if gt .Ahead 0 }}#35b5ff{{ end }}", + "{{ if gt .Behind 0 }}#f89cfa{{ end }}" + ], + "powerline_symbol": "\uE0B0", + "properties": { + "fetch_status": true, + "branch_max_length": 25, + "template": "{{ .HEAD }}{{ .BranchStatus }}" + } + }, + { + "type": "exit", + "style": "diamond", + "foreground": "#ffffff", + "background": "#00897b", + "background_templates": ["{{ if gt .Code 0 }}#e91e63{{ end }}"], + "leading_diamond": "", + "trailing_diamond": "\uE0B4", + "properties": { + "always_enabled": true, + "template": "\uE23A", + "prefix": "\uE0B0 " + } + } + ] + } + ] +} +``` diff --git a/docs/docs/config-overview.md b/docs/docs/config-overview.md index 1fdbcba5..b5548690 100644 --- a/docs/docs/config-overview.md +++ b/docs/docs/config-overview.md @@ -1,7 +1,7 @@ --- id: config-overview -title: Overview -sidebar_label: Overview +title: General +sidebar_label: General --- Oh My Posh renders your prompt based on the definition of _blocks_ (like Lego) which contain one or more _segments_. @@ -64,332 +64,7 @@ boxes with question marks, set up your terminal to use a [supported font][font] - terminal_background: `string` [color][colors] - terminal background color, set to your terminal's background color when you notice black elements in Windows Terminal or the Visual Studio Code integrated terminal -## Block - -Let's take a closer look at what defines a block. - -- type: `prompt` | `rprompt` -- newline: `boolean` -- alignment: `left` | `right` -- vertical_offset: `int` -- horizontal_offset: `int` -- segments: `array` of one or more `segments` - -### Type - -Tells the engine what to do with the block. There are three options: - -- `prompt` renders one or more segments -- `rprompt` renders one or more segments aligned to the right of the cursor. Only one `rprompt` block is permitted. -Supported on [ZSH][rprompt], Bash and Powershell. - -### Newline - -Start the block on a new line. Defaults to `false`. - -### Alignment - -Tell the engine if the block should be left or right-aligned. - -### Vertical offset - -Move the block up or down x lines. For example, `vertical_offset: 1` moves the prompt down one line, `vertical_offset: -1` -moves it up one line. - -### Horizontal offset - -Moves the segment to the left or the right to have it exactly where you want it to be. Works like `vertical_offset` -but on a horizontal level where a negative number moves the block left and a positive number right. - -### Segments - -Array of one or more segments. - -## Segment - -A segment is a part of the prompt with a certain context. There are different types available out-of-the-box, if you're -looking for what's included, feel free to skip this part and browse through the [segments][segments]. Keep reading to -understand how to configure a segment. - -- type: `string` any of the included [segments][segments] -- style: `powerline` | `plain` | `diamond` -- powerline_symbol: `string` -- invert_powerline: `boolean` -- leading_diamond: `string` -- trailing_diamond: `string` -- foreground: `string` [color][colors] -- foreground_templates: `array` of `string` values -- background: `string` [color][colors] -- background_templates: `array` of `string` values -- properties: `array` of `Property`: `string` - -### Type - -Takes the `string` value referencing which segment logic it needs to run (see [segments][segments] for possible values). - -### Style - -Oh Hi! You made it to a really interesting part, great! Style defines how a prompt is rendered. Looking at the most prompt -themes out there, we identified 3 types. All of these require a different configuration and depending on the look -you want to achieve you might need to understand/use them all. - -#### Powerline - -What started it all for us. Makes use of a single symbol (`powerline_symbol`) to separate the segments. It takes the -background color of the previous segment (or transparent if none) and the foreground of the current one (or transparent -if we're at the last segment). Expects segments to have a colored background, else there little use for this one. - -#### Plain - -Simple. Colored text on a transparent background. Make sure to set `foreground` for maximum enjoyment. -Segments will be separated by empty spaces unless you specify `''` for the `prefix` and `postfix` settings for the segment. - -#### Diamond - -While Powerline works great with a single symbol, sometimes you want a segment to have a different start and end symbol. -Just like a diamond: `< my segment text >`. The difference between this and plain is that the diamond symbols take the -segment background as their foreground color. - -### Powerline symbol - -Text character to use when `"style": "powerline"`. - -### Invert Powerline - -If `true` this swaps the foreground and background colors. Can be useful when the character you want does not exist -in the perfectly mirrored variant for example. - -### Leading diamond - -Text character to use at the start of the segment. Will take the background color of the segment as -its foreground color. - -### Trailing diamond - -Text character to use at the end of the segment. Will take the background color of the segment as its foreground color. - -### Foreground - -[Color][colors] to use as the segment text foreground color. Also supports transparency using the `transparent` keyword. - -### Foreground Templates - -Array if string templates to define the foreground color for the given Segment based on the Segment's Template Properties. -Under the hood this uses go's [text/template][go-text-template] feature extended with [sprig][sprig] and -offers a few standard properties to work with. For supported Segments, look for the **Template Properties** section in -the documentation. - -The following sample is based on the [AWS Segment][aws]. - -```json -{ - "type": "aws", - "style": "powerline", - "powerline_symbol": "\uE0B0", - "foreground": "#ffffff", - "background": "#111111", - "foreground_templates": [ - "{{if contains \"default\" .Profile}}#FFA400{{end}}", - "{{if contains \"jan\" .Profile}}#f1184c{{end}}" - ], - "properties": { - "prefix": " \uE7AD " - } -} -``` - -The logic is as follows: when `background_templates` contains an array, we will check every template line until there's -one that returns a non-empty string. So, when the contents of `.Profile` contain the word `default`, the first template -returns `#FFA400` and that's the color that will be used. If it contains `jan`, it returns `#f1184c`. When none of the -templates returns a value, the foreground value `#ffffff` is used. - -### Background - -[Color][colors] to use as the segment text background color. Also supports transparency using the `transparent` keyword. - -### Background Templates - -Same as [Foreground Templates][fg-templ] but for the background color. - -### Properties - -An array of **Properties** with a value. This is used inside of the segment logic to tweak what the output of the segment -will be. Segments have the ability to define their own Properties, but there are some general ones being used by the -engine which allow you to customize the output even more. - -#### General-purpose properties - -You can use these on any segment, the engine is responsible for adding them correctly. - -- prefix: `string` -- postfix: `string` -- include_folders: `[]string` -- exclude_folders: `[]string` - -##### Prefix - -The string content will be put in front of the segment's output text. Useful for symbols, text or other customizations. -If this is not set, it will be an empty space in `plain` mode. If you want to remove the space before the segment, -specify this as `''`. - -##### Postfix - -The string content will be put after the segment's output text. Useful for symbols, text or other customizations. -If this is not set, it will default to an empty space in `plain` mode. If you want to remove the space after the segment, -specify this as `''`. - -##### Include / Exclude Folders - -Sometimes you might want to have a segment only rendered in certain folders. If `include_folders` is specified, -the segment will only be rendered when in one of those locations. If `exclude_folders` is specified, the segment -will not be rendered when in one of the excluded locations. - -```json -"include_folders": [ - "/Users/posh/Projects" -] -``` - -```json -"exclude_folders": [ - "/Users/posh/Projects" -] -``` - -The strings specified in these properties are evaluated as [regular expressions][regex]. You -can use any valid regular expression construct, but the regular expression must match the entire directory -name. The following will match `/Users/posh/Projects/Foo` but not `/home/Users/posh/Projects/Foo`. - -```json -"include_folders": [ - "/Users/posh/Projects.*" -] -``` - -You can also combine these properties: - -```json -"include_folders": [ - "/Users/posh/Projects.*" -], -"exclude_folders": [ - "/Users/posh/Projects/secret-project.*" -] -``` - -##### Notes - -- Oh My Posh will accept both `/` and `\` as path separators for a folder and will match regardless of which -is used by the current operating system. -- Because the strings are evaluated as regular expressions, if you want to use a `\` in a Windows -directory name, you need to specify it as `\\\\`. -- The character `~` at the start of a specified folder will match the user's home directory. -- The comparison is case-insensitive on Windows and macOS, but case-sensitive on other operating systems. - -This means that for user Bill, who has a user account `Bill` on Windows and `bill` on Linux, `~/Foo` might match -`C:\Users\Bill\Foo` or `C:\Users\Bill\foo` on Windows but only `/home/bill/Foo` on Linux. - -## Full Sample - -```json -{ - "final_space": true, - "blocks": [ - { - "type": "prompt", - "alignment": "right", - "vertical_offset": -1, - "segments": [ - { - "type": "time", - "style": "plain", - "foreground": "#007ACC", - "properties": { - "time_format": "15:04:05" - } - } - ] - }, - { - "type": "prompt", - "alignment": "left", - "newline": true, - "segments": [ - { - "type": "session", - "style": "diamond", - "foreground": "#ffffff", - "background": "#ffb300", - "leading_diamond": "\uE0B6", - "trailing_diamond": "\uE0B0", - "properties": { - "postfix": " " - } - }, - { - "type": "path", - "style": "powerline", - "powerline_symbol": "\uE0B0", - "foreground": "#ffffff", - "background": "#61AFEF", - "properties": { - "prefix": " \uE5FF ", - "style": "folder", - "exclude_folders": [ - "/super/secret/project" - ], - "enable_hyperlink": false - } - }, - { - "type": "git", - "style": "powerline", - "foreground": "#193549", - "foreground_templates": [ - "{{ if and (gt .Ahead 0) (gt .Behind 0) }}#ffffff{{ end }}" - ], - "background": "#2e9599", - "background_templates": [ - "{{ if or (.Working.Changed) (.Staging.Changed) }}#f36943{{ end }}", - "{{ if and (gt .Ahead 0) (gt .Behind 0) }}#a8216b{{ end }}", - "{{ if gt .Ahead 0 }}#35b5ff{{ end }}", - "{{ if gt .Behind 0 }}#f89cfa{{ end }}" - ], - "powerline_symbol": "\uE0B0", - "properties": { - "fetch_status": true, - "branch_max_length": 25, - "template": "{{ .HEAD }}{{ .BranchStatus }}" - } - }, - { - "type": "exit", - "style": "diamond", - "foreground": "#ffffff", - "background": "#00897b", - "background_templates": ["{{ if gt .Code 0 }}#e91e63{{ end }}"], - "leading_diamond": "", - "trailing_diamond": "\uE0B4", - "properties": { - "always_enabled": true, - "template": "\uE23A", - "prefix": "\uE0B0 " - } - } - ] - } - ] -} -``` - [releases]: https://github.com/JanDeDobbeleer/oh-my-posh/releases/latest [font]: /docs/config-fonts [schema]: https://github.com/JanDeDobbeleer/oh-my-posh/blob/main/themes/schema.json [themes]: https://github.com/JanDeDobbeleer/oh-my-posh/tree/main/themes -[segments]: /docs/battery -[colors]: /docs/config-colors -[go-text-template]: https://golang.org/pkg/text/template/ -[sprig]: https://masterminds.github.io/sprig/ -[fg-templ]: /docs/config-overview#foreground-templates -[regex]: https://www.regular-expressions.info/tutorial.html -[aws]: /docs/aws diff --git a/docs/docs/config-segment.md b/docs/docs/config-segment.md new file mode 100644 index 00000000..08a66e44 --- /dev/null +++ b/docs/docs/config-segment.md @@ -0,0 +1,219 @@ +--- +id: config-segment +title: Segment +sidebar_label: Segment +--- + +A segment is a part of the prompt with a certain context. There are different types available out-of-the-box, if you're +looking for what's included, feel free to skip this part and browse through the [segments][segments]. Keep reading to +understand how to configure a segment. + +```json +{ + "$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json", + ... + "blocks": [ + { + ... + "segments": [ + { + "type": "path", + "style": "powerline", + "powerline_symbol": "\uE0B0", + "foreground": "#ffffff", + "background": "#61AFEF", + "properties": { + ... + } + } + ] + } + ] +} +``` + +- type: `string` any of the included [segments][segments] +- style: `powerline` | `plain` | `diamond` +- powerline_symbol: `string` +- invert_powerline: `boolean` +- leading_diamond: `string` +- trailing_diamond: `string` +- foreground: `string` [color][colors] +- foreground_templates: `array` of `string` values +- background: `string` [color][colors] +- background_templates: `array` of `string` values +- properties: `array` of `Property`: `string` + +## Type + +Takes the `string` value referencing which segment logic it needs to run (see [segments][segments] for possible values). + +## Style + +Oh Hi! You made it to a really interesting part, great! Style defines how a prompt is rendered. Looking at the most prompt +themes out there, we identified 3 types. All of these require a different configuration and depending on the look +you want to achieve you might need to understand/use them all. + +### Powerline + +What started it all for us. Makes use of a single symbol (`powerline_symbol`) to separate the segments. It takes the +background color of the previous segment (or transparent if none) and the foreground of the current one (or transparent +if we're at the last segment). Expects segments to have a colored background, else there little use for this one. + +### Plain + +Simple. Colored text on a transparent background. Make sure to set `foreground` for maximum enjoyment. +Segments will be separated by empty spaces unless you specify `''` for the `prefix` and `postfix` settings for the segment. + +### Diamond + +While Powerline works great with a single symbol, sometimes you want a segment to have a different start and end symbol. +Just like a diamond: `< my segment text >`. The difference between this and plain is that the diamond symbols take the +segment background as their foreground color. + +## Powerline symbol + +Text character to use when `"style": "powerline"`. + +## Invert Powerline + +If `true` this swaps the foreground and background colors. Can be useful when the character you want does not exist +in the perfectly mirrored variant for example. + +## Leading diamond + +Text character to use at the start of the segment. Will take the background color of the segment as +its foreground color. + +## Trailing diamond + +Text character to use at the end of the segment. Will take the background color of the segment as its foreground color. + +## Foreground + +[Color][colors] to use as the segment text foreground color. Also supports transparency using the `transparent` keyword. + +## Foreground Templates + +Array if string templates to define the foreground color for the given Segment based on the Segment's Template Properties. +Under the hood this uses go's [text/template][go-text-template] feature extended with [sprig][sprig] and +offers a few standard properties to work with. For supported Segments, look for the **Template Properties** section in +the documentation. + +The following sample is based on the [AWS Segment][aws]. + +```json +{ + "type": "aws", + "style": "powerline", + "powerline_symbol": "\uE0B0", + "foreground": "#ffffff", + "background": "#111111", + "foreground_templates": [ + "{{if contains \"default\" .Profile}}#FFA400{{end}}", + "{{if contains \"jan\" .Profile}}#f1184c{{end}}" + ], + "properties": { + "prefix": " \uE7AD " + } +} +``` + +The logic is as follows: when `background_templates` contains an array, we will check every template line until there's +one that returns a non-empty string. So, when the contents of `.Profile` contain the word `default`, the first template +returns `#FFA400` and that's the color that will be used. If it contains `jan`, it returns `#f1184c`. When none of the +templates returns a value, the foreground value `#ffffff` is used. + +## Background + +[Color][colors] to use as the segment text background color. Also supports transparency using the `transparent` keyword. + +## Background Templates + +Same as [Foreground Templates][fg-templ] but for the background color. + +## Properties + +An array of **Properties** with a value. This is used inside of the segment logic to tweak what the output of the segment +will be. Segments have the ability to define their own Properties, but there are some general ones being used by the +engine which allow you to customize the output even more. + +### General-purpose properties + +You can use these on any segment, the engine is responsible for adding them correctly. + +- prefix: `string` +- postfix: `string` +- include_folders: `[]string` +- exclude_folders: `[]string` + +#### Prefix + +The string content will be put in front of the segment's output text. Useful for symbols, text or other customizations. +If this is not set, it will be an empty space in `plain` mode. If you want to remove the space before the segment, +specify this as `''`. + +#### Postfix + +The string content will be put after the segment's output text. Useful for symbols, text or other customizations. +If this is not set, it will default to an empty space in `plain` mode. If you want to remove the space after the segment, +specify this as `''`. + +#### Include / Exclude Folders + +Sometimes you might want to have a segment only rendered in certain folders. If `include_folders` is specified, +the segment will only be rendered when in one of those locations. If `exclude_folders` is specified, the segment +will not be rendered when in one of the excluded locations. + +```json +"include_folders": [ + "/Users/posh/Projects" +] +``` + +```json +"exclude_folders": [ + "/Users/posh/Projects" +] +``` + +The strings specified in these properties are evaluated as [regular expressions][regex]. You +can use any valid regular expression construct, but the regular expression must match the entire directory +name. The following will match `/Users/posh/Projects/Foo` but not `/home/Users/posh/Projects/Foo`. + +```json +"include_folders": [ + "/Users/posh/Projects.*" +] +``` + +You can also combine these properties: + +```json +"include_folders": [ + "/Users/posh/Projects.*" +], +"exclude_folders": [ + "/Users/posh/Projects/secret-project.*" +] +``` + +#### Notes + +- Oh My Posh will accept both `/` and `\` as path separators for a folder and will match regardless of which +is used by the current operating system. +- Because the strings are evaluated as regular expressions, if you want to use a `\` in a Windows +directory name, you need to specify it as `\\\\`. +- The character `~` at the start of a specified folder will match the user's home directory. +- The comparison is case-insensitive on Windows and macOS, but case-sensitive on other operating systems. + +This means that for user Bill, who has a user account `Bill` on Windows and `bill` on Linux, `~/Foo` might match +`C:\Users\Bill\Foo` or `C:\Users\Bill\foo` on Windows but only `/home/bill/Foo` on Linux. + +[segments]: /docs/battery +[colors]: /docs/config-colors +[go-text-template]: https://golang.org/pkg/text/template/ +[sprig]: https://masterminds.github.io/sprig/ +[fg-templ]: /docs/config-overview#foreground-templates +[regex]: https://www.regular-expressions.info/tutorial.html +[aws]: /docs/aws diff --git a/docs/docs/segment-environment.md b/docs/docs/segment-environment.md index f35bc87e..982a0a52 100644 --- a/docs/docs/segment-environment.md +++ b/docs/docs/segment-environment.md @@ -34,7 +34,7 @@ New-Alias -Name 'Set-PoshContext' -Value 'Set-EnvVar' -Scope Global -Force The segment will show when the value of the environment variable isn't empty. -## Sample Configuration +## Sample *Configuration* ```json { diff --git a/docs/sidebars.js b/docs/sidebars.js index a75163ee..8f151a2c 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -20,6 +20,9 @@ module.exports = { label: "⚙️ Configuration", items: [ "config-overview", + "config-block", + "config-segment", + "config-sample", "config-title", "config-colors", "config-text-style",