mirror of
https://github.com/JanDeDobbeleer/oh-my-posh.git
synced 2025-01-13 20:27:28 -08:00
docs: yaml/toml documentation
This commit is contained in:
ehawman-rosenberg
Jan De Dobbeleer
parent
73653ab03b
commit
1aa7e058f8
|
|
@ -4,8 +4,22 @@ title: Block
|
|||
sidebar_label: Block
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem"
|
||||
|
||||
Let's take a closer look at what defines a block.
|
||||
|
||||
<Tabs
|
||||
defaultValue="json"
|
||||
groupId="sample"
|
||||
values={[
|
||||
{ label: 'json', value: 'json', },
|
||||
{ label: 'yaml', value: 'yaml', },
|
||||
{ label: 'toml', value: 'toml', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="json">
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json",
|
||||
|
|
@ -22,6 +36,37 @@ Let's take a closer look at what defines a block.
|
|||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="yaml">
|
||||
|
||||
```yaml
|
||||
# yaml-language-server: $schema=https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json
|
||||
...
|
||||
blocks:
|
||||
- type: prompt
|
||||
alignment: left
|
||||
segments: [
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="toml">
|
||||
|
||||
```toml
|
||||
"$schema" = "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json"
|
||||
|
||||
[[blocks]]
|
||||
type = "prompt"
|
||||
alignment = "left"
|
||||
segments = [
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
- type: `prompt` | `rprompt`
|
||||
- newline: `boolean`
|
||||
- alignment: `left` | `right`
|
||||
|
|
|
|||
|
|
@ -4,6 +4,20 @@ title: Sample
|
|||
sidebar_label: Sample
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem"
|
||||
|
||||
<Tabs
|
||||
defaultValue="json"
|
||||
groupId="sample"
|
||||
values={[
|
||||
{ label: 'json', value: 'json', },
|
||||
{ label: 'yaml', value: 'yaml', },
|
||||
{ label: 'toml', value: 'toml', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="json">
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json",
|
||||
|
|
@ -94,3 +108,154 @@ sidebar_label: Sample
|
|||
"version": 2
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="yaml">
|
||||
|
||||
```yaml
|
||||
# yaml-language-server: $schema=https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json
|
||||
blocks:
|
||||
- alignment: right
|
||||
segments:
|
||||
- foreground: "#007ACC"
|
||||
template: " {{ .CurrentDate | date .Format }} "
|
||||
properties:
|
||||
time_format: '15:04:05'
|
||||
style: plain
|
||||
type: time
|
||||
type: prompt
|
||||
vertical_offset: -1
|
||||
- alignment: left
|
||||
newline: true
|
||||
segments:
|
||||
- background: "#ffb300"
|
||||
foreground: "#ffffff"
|
||||
leading_diamond: "\ue0b6"
|
||||
template: " {{ .UserName }} "
|
||||
style: diamond
|
||||
trailing_diamond: "\ue0b0"
|
||||
type: session
|
||||
- background: "#61AFEF"
|
||||
foreground: "#ffffff"
|
||||
powerline_symbol: "\ue0b0"
|
||||
template: " {{ .Path }} "
|
||||
properties:
|
||||
exclude_folders:
|
||||
- "/super/secret/project"
|
||||
style: folder
|
||||
style: powerline
|
||||
type: path
|
||||
- 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 }}"
|
||||
foreground: "#193549"
|
||||
foreground_templates:
|
||||
- "{{ if and (gt .Ahead 0) (gt .Behind 0) }}#ffffff{{ end }}"
|
||||
powerline_symbol: "\ue0b0"
|
||||
template: " {{ .HEAD }}{{ .BranchStatus }} "
|
||||
properties:
|
||||
branch_max_length: 25
|
||||
fetch_status: true
|
||||
style: powerline
|
||||
type: git
|
||||
- background: "#00897b"
|
||||
background_templates:
|
||||
- "{{ if gt .Code 0 }}#e91e63{{ end }}"
|
||||
foreground: "#ffffff"
|
||||
template: "<parentBackground>\ue0b0</> \ue23a "
|
||||
properties:
|
||||
always_enabled: true
|
||||
style: diamond
|
||||
trailing_diamond: "\ue0b4"
|
||||
type: exit
|
||||
type: prompt
|
||||
final_space: true
|
||||
version: 2
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="toml">
|
||||
|
||||
```toml
|
||||
"$schema" = "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json"
|
||||
final_space = true
|
||||
version = 2
|
||||
|
||||
[[blocks]]
|
||||
alignment = "right"
|
||||
type = "prompt"
|
||||
vertical_offset = -1
|
||||
|
||||
[[blocks.segments]]
|
||||
foreground = "#007ACC"
|
||||
template = " {{ .CurrentDate | date .Format }} "
|
||||
style = "plain"
|
||||
type = "time"
|
||||
|
||||
[blocks.segments.properties]
|
||||
time_format = "15:04:05"
|
||||
|
||||
[[blocks]]
|
||||
alignment = "left"
|
||||
newline = true
|
||||
type = "prompt"
|
||||
|
||||
[[blocks.segments]]
|
||||
background = "#ffb300"
|
||||
foreground = "#ffffff"
|
||||
leading_diamond = "\ue0b6"
|
||||
template = " {{ .UserName }} "
|
||||
style = "diamond"
|
||||
trailing_diamond = "\ue0b0"
|
||||
type = "session"
|
||||
|
||||
[[blocks.segments]]
|
||||
background = "#61AFEF"
|
||||
foreground = "#ffffff"
|
||||
powerline_symbol = "\ue0b0"
|
||||
template = " {{ .Path }} "
|
||||
style = "powerline"
|
||||
type = "path"
|
||||
|
||||
[blocks.segments.properties]
|
||||
exclude_folders = [ "/super/secret/project" ]
|
||||
style = "folder"
|
||||
|
||||
[[blocks.segments]]
|
||||
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 }}"
|
||||
]
|
||||
foreground = "#193549"
|
||||
foreground_templates = [ "{{ if and (gt .Ahead 0) (gt .Behind 0) }}#ffffff{{ end }}" ]
|
||||
powerline_symbol = "\ue0b0"
|
||||
template = " {{ .HEAD }}{{ .BranchStatus }} "
|
||||
style = "powerline"
|
||||
type = "git"
|
||||
|
||||
[blocks.segments.properties]
|
||||
branch_max_length = 25
|
||||
fetch_status = true
|
||||
|
||||
[[blocks.segments]]
|
||||
background = "#00897b"
|
||||
background_templates = [ "{{ if gt .Code 0 }}#e91e63{{ end }}" ]
|
||||
foreground = "#ffffff"
|
||||
template = "<parentBackground>\ue0b0</> \ue23a "
|
||||
style = "diamond"
|
||||
trailing_diamond = "\ue0b4"
|
||||
type = "exit"
|
||||
|
||||
[blocks.segments.properties]
|
||||
always_enabled = true
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
|
|
|||
|
|
@ -4,6 +4,9 @@ title: General
|
|||
sidebar_label: General
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem"
|
||||
|
||||
Oh My Posh renders your prompt based on the definition of _blocks_ (like Lego) which contain one or more _segments_.
|
||||
A really simple configuration could look like this. The default format is `json`, but we also support `toml` and `yaml`.
|
||||
There's a [schema][schema] available which is kept up-to-date and helps with autocomplete and validation of the configuration.
|
||||
|
|
@ -13,6 +16,17 @@ There are a few [themes][themes] available which are basically predefined config
|
|||
starting point to create your own configuration.
|
||||
:::
|
||||
|
||||
<Tabs
|
||||
defaultValue="json"
|
||||
groupId="sample"
|
||||
values={[
|
||||
{ label: 'json', value: 'json', },
|
||||
{ label: 'yaml', value: 'yaml', },
|
||||
{ label: 'toml', value: 'toml', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="json">
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json",
|
||||
|
|
@ -38,9 +52,53 @@ starting point to create your own configuration.
|
|||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="yaml">
|
||||
|
||||
```yaml
|
||||
# yaml-language-server: $schema=https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json
|
||||
final_space: true
|
||||
blocks:
|
||||
- type: prompt
|
||||
alignment: left
|
||||
segments:
|
||||
- type: path
|
||||
style: powerline
|
||||
powerline_symbol: ""
|
||||
foreground: "#ffffff"
|
||||
background: "#61AFEF"
|
||||
properties:
|
||||
style: folder
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="toml">
|
||||
|
||||
```toml
|
||||
"$schema" = "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json"
|
||||
final_space = true
|
||||
|
||||
[[blocks]]
|
||||
type = "prompt"
|
||||
alignment = "left"
|
||||
|
||||
[[blocks.segments]]
|
||||
type = "path"
|
||||
style = "powerline"
|
||||
powerline_symbol = ""
|
||||
foreground = "#ffffff"
|
||||
background = "#61AFEF"
|
||||
|
||||
[blocks.segments.properties]
|
||||
style = "folder"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
With this configuration, a single powerline segment is rendered that shows the name of the folder you're currently in.
|
||||
To set this configuration in combination with a Oh My Posh [executable][releases], use the `--config` flag to
|
||||
set a path to a JSON file containing the above code. The `--shell universal` flag is used to print the prompt without
|
||||
set a path to a file containing the above code. The `--shell universal` flag is used to print the prompt without
|
||||
escape characters to see the prompt as it would be shown inside a prompt function for your shell.
|
||||
|
||||
:::caution
|
||||
|
|
@ -71,8 +129,53 @@ For example, the following is a valid `--config` flag:
|
|||
you notice black elements in Windows Terminal or the Visual Studio Code integrated terminal
|
||||
- accent_color: `string` [color][colors] - accent color, used as a fallback when the `accent` [color][accent] is not supported
|
||||
|
||||
### JSON Schema Validation
|
||||
|
||||
As mentioned above, Oh My Posh themes can utilize JSON Schema to validate their contents. Themes should include a link to
|
||||
the [external schema document][schema] which prescribes the appropriate structure and contents for various elements. If
|
||||
your code editor is configured to use JSON Schema, it will compare your custom theme to the external document, and issue
|
||||
warnings for discrepancies.
|
||||
|
||||
For example, given the following code:
|
||||
|
||||
```json
|
||||
...
|
||||
"segments": [
|
||||
{
|
||||
"type": "an_invalid_entry",
|
||||
"template": "{{ if gt .Code 0 }}\uf134{{ end }}",
|
||||
}
|
||||
]
|
||||
...
|
||||
```
|
||||
|
||||
Warnings will be raised for type, since `an_invalid_entry` is not in the list of acceptable values, as well as
|
||||
for the entire segment item (enclosed in {}), since it lacks the required `style` key. Take advantage of these
|
||||
warnings, and ignore them at your peril.
|
||||
|
||||
### Accepted Formats
|
||||
|
||||
Oh My Posh supports three file formats for themes: `json`, `yaml`, and `toml`.
|
||||
|
||||
Various converters exist to convert between these, although they aren't perfect and will require manaual
|
||||
adjustment. Notably, the schema implementation for json is as follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json"
|
||||
}
|
||||
```
|
||||
|
||||
While for yaml:
|
||||
|
||||
```yaml
|
||||
# yaml-language-server: $schema=https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json
|
||||
```
|
||||
|
||||
Converters won't catch this change, so you will need to adjust manually.
|
||||
|
||||
[releases]: https://github.com/JanDeDobbeleer/oh-my-posh/releases/latest
|
||||
[font]: /docs/installation/fonts
|
||||
[font]: /docs/configuration/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
|
||||
[colors]: /docs/configuration/colors
|
||||
|
|
|
|||
|
|
@ -138,7 +138,7 @@ Maybe there's a theme you like, but you don't fancy the colors. Or, maybe there'
|
|||
want to tweak/add, or replace some of the icons with a different one. Whatever the case, **read through
|
||||
available options first**, by starting with the [configuration guide][configuration].
|
||||
|
||||
You can export the current theme (default, or set via `--config`) to the format you like (`json` or `toml`)
|
||||
You can export the current theme (default, or set via `--config`) to the format you like (`json`, `yaml`, or `toml`)
|
||||
which can be used to tweak and store as your own custom theme.
|
||||
|
||||
|
||||
|
|
@ -146,8 +146,14 @@ which can be used to tweak and store as your own custom theme.
|
|||
oh-my-posh config export --output ~/.mytheme.omp.json
|
||||
```
|
||||
|
||||
### Read the docs
|
||||
|
||||
To fully understand how to customize a theme, read through the documentation in the configuration and segments sections.
|
||||
The [configuration][configuration] section covers the basic building blocks and concepts of Oh My Posh themes, while the
|
||||
segments section covers how to configure each available segment.
|
||||
|
||||
[themes]: themes.md
|
||||
[configuration]: configuration/overview.md
|
||||
[default-theme]: https://github.com/JanDeDobbeleer/oh-my-posh/blob/main/themes/default.omp.json
|
||||
[jandedobbeleer]: /docs/themes#jandedobbeleer
|
||||
[json-schema]: https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json
|
||||
|
|
@ -15,7 +15,7 @@ module.exports = {
|
|||
],
|
||||
themeConfig: {
|
||||
prism: {
|
||||
additionalLanguages: ['powershell', 'lua', 'jsstacktrace'],
|
||||
additionalLanguages: ['powershell', 'lua', 'jsstacktrace', 'toml'],
|
||||
},
|
||||
navbar: {
|
||||
title: 'Oh My Posh',
|
||||
|
|
|
|||
Loading…
Reference in a new issue