docs: yaml/toml documentation

website/docs/configuration/block.mdx

@@ -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`

website/docs/configuration/example.mdx

@@ -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>
+

website/docs/configuration/overview.mdx

@@ -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

website/docs/installation/customize.mdx

@@ -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

website/docusaurus.config.js

@@ -15,7 +15,7 @@ module.exports = {
   ],
   themeConfig: {
     prism: {
-      additionalLanguages: ['powershell', 'lua', 'jsstacktrace'],
+      additionalLanguages: ['powershell', 'lua', 'jsstacktrace', 'toml'],
     },
     navbar: {
       title: 'Oh My Posh',