Text editor plugins for Salt states and YAML/Jinja
Tags: devops, yaml, saltstack, salt
Published: 2018-12-11 13:34:56

---
title: Text editor plugins for Salt states and YAML/Jinja
published: true
tags: devops, yaml, saltstack, salt
canonical_url: https://salt.tips/text-editor-plugins-for-salt-states-and-yaml-jinja/
cover_image: https://salt.tips/text-editor-plugins-for-salt-states-and-yaml-jinja/yaml-ruler-cover.jpg
description: Salt and YAML/Jinja plugins for Vim, Emacs, Sublime Text, Atom, Visual Studio Code, PyCharm, Kate, MC and Eclipse
---

<figcaption><em>Image by <a href="https://twitter.com/Caged/status/1039937162769096704">Justin Palmer</a></em></figcaption>

If you have ever written a couple of Salt states, these problems may sound familiar:

- A missing colon after the YAML key or a missing space after the colon
- Data failed to compile: State ‘foo’ in SLS ‘bar’ is not formed as a list
- A ParserError or ScannerError while running the `state.highstate`
- A nested dictionary, indented with two spaces instead of four
- State requirements at the wrong indentation level
- Indentation with mixed tabs and spaces, which took a surprisingly long time to debug

And even if your states are valid YAML, they still can have no sense for Salt because your `wathc_in` requisite has a typo. Sprinkle a few Jinja tags here and there, and the errors can get even fancier…

#### Is there anything that could be done?

These issues definitely have come up before ([#802](https://github.com/saltstack/salt/issues/802)). Smart developers probably have this figured out, right?

Indeed, it is possible to validate your states, in a semi- or completely automated way, even before they touch your infrastructure. For Salt, you have the following options:

1. Use the [`salt-call --local --retcode-passthrough state.show_sls YOUR_STATE`](https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.state.html#salt.modules.state.show_sls) either manually or using a commit hook. This triggers the state rendering process and can catch tons of possible errors.

2. Test your states using Test Kitchen together with [kitchen-salt](https://github.com/saltstack/kitchen-salt) and some verifier. A helpful guide on this topic is available [here](https://salt-formulas.readthedocs.io/en/latest/develop/testing-formulas.html)

However, all of this feels a bit heavy. You need to commit and push to run your tests, spin up VMs or containers, dive into Ruby code, and write tests for all possible pillar/grain permutations. Such a long feedback cycle could easily lead to [`git commit -m "Fuck YAML"`](https://github.com/search?q=fuck+yaml&type=Commits) in your commit history and a subsequent amend/rebase/squash dance (and you can’t squash the obscene commit notifications sent to the rest of your team!).

#### Is there something more lightweight?

Well, your development environment can help you. The first layer of defense can work right in your text editor as you type, providing immediate feedback. It will catch your typos before they get committed and deployed (and let the CI system deal with more complicated stuff). An ideal editor plugin can:

- Help you deal with YAML indentation levels and data structures
- Know and highlight the most common Salt state keywords
- Highlight Jinja brackets and tags
- Autocomplete the keywords

Below I’ll cover plugins for 9 different editors, so you do not have to switch away from your favorite one. Also, I will give a few installation/configuration tips to save you some googling. These plugins aren’t ideal, but they are open source, and you can contribute to any of them if you want (I [did](https://github.com/glynnforrest/salt-mode/pull/21)).

- [Atom](#atom)
- [Eclipse](#eclipse)
- [Emacs](#emacs)
- [Kate](#kate)
- [Midnight Commander](#midnight-commander)
- [Sublime Text](#sublime-text)
- [PyCharm](#pycharm)
- [Vim](#vim)
- [Visual Studio Code](#visual-studio-code)
- [Final tips](#final-tips)

If your favorite editor is not covered here, or you want to share a nifty hack that helps you reduce the number of YAML mistakes, ping me on [Twitter](https://twitter.com/intent/tweet?in_reply_to=1073154585055952896).

## Atom

![SaltStack package for Atom](https://salt.tips/text-editor-plugins-for-salt-states-and-yaml-jinja/salt-atom.png)

Out of the box, Atom understands `*.sls` files as YAML. Plus, you could install [atom-jinja2](https://atom.io/packages/atom-jinja2) and manually switch a file grammar to `YAML (Jinja Templates)` by pressing `Ctrl+Shift+L`.

For better results, you can install both [atom-salt](https://github.com/saltstack/atom-salt) and [atom-jinja2](https://github.com/danielchatfield/atom-jinja2). Just click `Edit -> Preferences -> Install`, search for `atom-salt` or `atom-jinja` and install them.

#### Features

- The first `atom-salt` language scope is `source.yaml.salt`, which is automatically enabled for `*.sls` files and provides syntax highlighting (YAML+Jinja combo)
- The second scope `source.python.salt` is not associated with any file extension and instead is enabled for any files which start with `#!py`. This means you get syntax highlighting for `py`, `pydsl`, and `pyobjects` Salt renderers.
- Also, it should open Salt docs via the `salt-doc` command, but it didn’t work for me for some reason
- `Atom-jinja2` provides the `source.yaml.jinja` scope, which is enabled for `*.jinja`, `*.j2` and a bunch of [other extensions](https://github.com/danielchatfield/atom-jinja2#new-syntax-definintions)
- Supports syntax highlighting and folding
- Has a couple of Jinja-related [snippets](https://github.com/danielchatfield/atom-jinja2/blob/master/snippets/atom-jinja2.cson)

You can assign specific language scope to any extension with something like this in your `~/.atom/config.cson`:

```
"*":
  core:
    customFileTypes:
      "source.python.salt": [
        "py.sls"
        "pysls"
      ]
```

#### Other things to try

- [Language-salt](https://atom.io/packages/language-salt) - an alternative Atom plugin for Salt (enabled for `*.sls` files, provides the `source.salt` scope and a bunch of [snippets](https://github.com/JonGretar/language-salt/blob/master/snippets/language-salt.cson))
- [Aligner-salt](https://atom.io/packages/aligner-salt) ([GitHub](https://github.com/adrianlee44/atom-aligner-salt)) to visually align YAML attributes
- The indentation guides should be enabled by default by Salt plugin, but you can enforce it by clicking `Edit -> Preferences -> Editor -> Show Indent Guide`

## Eclipse

![SaltStack plugin for Eclipse](https://salt.tips/text-editor-plugins-for-salt-states-and-yaml-jinja/salt-eclipse.png)

I was unable to find a good enough solution for Eclipse, but below are two directions you can try to explore:

1. Go to `Help -> Eclipse Marketplace`, search for [“yedit”](https://github.com/oyse/yedit) and install it. Then go to `Window -> Preferences -> General -> Editors -> File Associations` and associate the `*.sls` extension with YEdit. This enables syntax highlighting for plain YAML files (no luck with Jinja though).

2. Another plugin is called [LiClipseText](http://www.liclipse.com/text/supported_languages.html). It has support for both YAML and Jinja syntaxes, but can’t enable them simultaneously for a single file. It should be possible though, and there are [some hints](https://github.com/fabioz/LiClipseText/issues/13) if you want to contribute.

Indentation guides are available via a separate [indent-guide](https://marketplace.eclipse.org/content/indent-guide) plugin.

## Emacs

![SaltStack mode for Emacs](https://salt.tips/text-editor-plugins-for-salt-states-and-yaml-jinja/salt-emacs.png)

[Salt-mode](https://github.com/glynnforrest/salt-mode) is your best bet. It is based on `yaml-mode` and `mmm-mode` and is automatically enabled for `*.sls` files. The simplest way to install is through MELPA.

#### Features

- Syntax highlighting for `*.sls` files (also possible to enable `*.jinja` syntax support)
- Indentation and alignment of expressions and statements
- Spell checking of comments with `flyspell`
- Use `salt-mode-browse-doc` to browse the documentation of the state module at point
- Quickly move between Salt state functions

#### Things to be aware of

- No auto-completion [yet](https://github.com/glynnforrest/salt-mode/issues/17)
- It uses [yaml-mode](https://github.com/yoshiki/yaml-mode/) under the hood, which needs a new maintainer. If you are willing to step in, there are a number of [issues](https://github.com/yoshiki/yaml-mode/issues) for you to fix.

#### Other things to try

- [Indent-tools](https://gitlab.com/emacs-stuff/indent-tools) together with [hydra](https://github.com/abo-abo/hydra) looks like a good combo for whitespace-sensitive languages like YAML and Python.
- [Highlight-indent-guides](https://github.com/DarthFennec/highlight-indent-guides) is worth looking at (although it adds more visual clutter). Also, there is a [crosshair highlighting](https://www.emacswiki.org/emacs/CrosshairHighlighting) mode.
- Install [dash-at-point](https://github.com/stanaka/dash-at-point) if you use [Dash API Documentation Browser](https://kapeli.com/dash)
- To highlight other Jinja-templated configuration files, establish the convention of naming them using the `*.jinja` extension and add the following lines to your `init.el` (see the [README](https://raw.githubusercontent.com/purcell/mmm-mode/master/README) for more details):

```
(mmm-add-mode-ext-class nil "\\.jinja\\'" 'jinja2)
```

## Kate

![SaltStack syntax highlighter for Kate](https://salt.tips/text-editor-plugins-for-salt-states-and-yaml-jinja/salt-kate.png)

[Kate-jinja2-highlighting](https://github.com/Pitmairen/kate-jinja2-highlighting) has a bunch of syntax highlighters for different file types with Jinja on top.

#### Features

- Highlights `*.jinja`, `*.jinja2` and `*.j2` using Jinja2 syntax
- Highlights `*.yaml`, `*.yml` and `*.sls` files using YAML+Jinja2 syntax (if you apply the patch below)
- If you want to enable indentation guide, toggle the `Settings -> Configure Kate -> Editor Component -> Appearance -> Show indentation lines`

To install it, copy the `*.xml` files into the `~/.local/share/org.kde.syntax-highlighting/syntax/` folder. Then go to `Settings -> Configure Kate -> Editor Component -> Open/Save -> Modes & Filetypes`, select `Markup/Jinja2/YAML`, open the `Variables` drop-down, and then set both `indent-width` `tab-width` to `2` and `Indent using` to `Spaces`.

You also need to associate `*.sls` files with the syntax highlighter:

```
sed -i'' -e 's/\(\*\.yml\)"/\1;*.sls"/' yaml-jinja2.xml
```

The `sed` command above is equivalent to the patch below:

```
--- yaml-jinja2.xml.orig	2018-10-25 02:39:31.000000000 +0700
+++ yaml-jinja2.xml	2018-10-25 02:39:40.000000000 +0700
@@ -3,7 +3,7 @@
 <!-- Author: Dr Orlovsky MA <maxim@orlovsky.info> //-->
 <!-- Autogenerated from yaml.xml -->
 <language name="Jinja2/YAML" version="1.2" kateversion="2.3" section="Markup"
- extensions="*.yaml;*.yml" mimetype="text/yaml"
+ extensions="*.yaml;*.yml;*.sls" mimetype="text/yaml"
           author="Dr Orlovsky MA (dr.orlovsky@gmail.com)" license="LGPL">
   <highlighting>
     <contexts>
```

## Midnight Commander

![SaltStack syntax highlighter for Midnight Commander](https://salt.tips/text-editor-plugins-for-salt-states-and-yaml-jinja/salt-midnight-commander.png)

Midnight Commander is an oldie but goodie for those of us who used [orthodox file managers](https://en.wikipedia.org/wiki/File_manager#Orthodox_file_managers) back in the 90’s and can’t live without one. Personally, I use it to quickly navigate the filesystem tree and view the files without opening them in my primary editor. According to [this ticket](https://midnight-commander.org/ticket/3293), out of the box, `mcedit` highlights `*.yml` and `*.yaml` files and understands simple Jinja variables (no support for tags though). Also, it does not understand `*.jinja` files.

To enable `*.sls` highlighting you need to make a copy of the default `Syntax` file and tweak it a bit:

```
mkdir -p ~/.config/mc/mcedit
sed -e 's/\(|YML)\)/|sls\1/' /usr/share/mc/syntax/Syntax > ~/.config/mc/mcedit/Syntax
```

The `sed` command above is equivalent to the patch below:

```
--- /home/user/.config/mc/mcedit/Syntax.orig 2017-08-05 04:03:29.000000000 +0700
+++ /home/user/.config/mc/mcedit/Syntax	2018-10-10 19:50:11.390542735 +0700
@@ -271,7 +271,7 @@
 file ..\*\\.cl$ OpenCL\sProgram
 include opencl.syntax
 
-file ..\*\\.(ya?ml|YML)$ YAML\sFile
+file ..\*\\.(ya?ml|sls|YML)$ YAML\sFile
 include yaml.syntax
 
 file .\*\\.osl$ OSL\sProgram
```

## PyCharm

![SaltStack support in PyCharm](https://salt.tips/text-editor-plugins-for-salt-states-and-yaml-jinja/salt-pycharm.png)

Well, it looks there are [no](https://github.com/vermut/intellij-snakeyaml/issues/14) Salt-specific plugins for PyCharm. Ansible users are luckier here - PyCharm has support for [JSON Schemas](http://schemastore.org/json/), and someone from RedHat has created [one](https://github.com/shaded-enmity/ansible-schema-generator). This means code auto-completion for Ansible-specific YAML data structures right out of the box! Plus, there is a separate [YAML/Ansible](https://plugins.jetbrains.com/plugin/7792-yaml-ansible-support) plugin ([GitHub](https://github.com/vermut/intellij-ansible/)).

However (aside from using Ansible plugins), you can tweak PyCharm to make it work with Salt states. Click `File -> Settings -> Languages & Frameworks -> Python Template Languages`, select `Jinja2` in the `Template language` drop-down, click the “+” button and select `YAML`. This should enable syntax highlighting for YAML+Jinja combo. To associate it with the `*.sls` files, go to `File -> Settings -> Editor -> File Types`, find `YAML` and add the `*.sls` extension.

#### Other features

- You can reformat YAML code with the `Reformat Code` action or via a shortcut: `Cmd + Alt + L` on MacOS / `Ctrl + Alt + L` on Windows and Linux
- To customize YAML code style settings, visit `File -> Settings -> Editor -> Code Style -> YAML`
- Indentation guides are enabled by default, but you can disable them via `File -> Settings -> Editor -> General -> Appearance -> Show indent guides`

## Sublime Text

![SaltStack plugin for Sublime Text](https://salt.tips/text-editor-plugins-for-salt-states-and-yaml-jinja/salt-sublime-text.png)

The extension is available on [GitHub](https://github.com/saltstack/sublime-text). To install it click `Preferences -> Package Control -> Install Package`, search for `saltstack` and click to install. It is also recommended to install the [separate extension](https://github.com/kudago/jinja2-tmbundle) for Jinja (go to `Package Control` and search for `jinja2`).

#### Features

- Syntax highlighting for `*.sls` files
- Syntax highlighting for `*.j2` files if you install the Jinja extension
- Several [snippets](https://github.com/saltstack/sublime-text/tree/master/Snippets/Jinja) for Jinja (forked from [sublime-jinja2](https://github.com/jpvanhal/sublime-jinja2))
- Several [snippets](https://github.com/saltstack/sublime-text/tree/master/Snippets/SaltStack) for often used Salt state modules like `file` and `pkg`

Indentation guides are enabled by default, but you may also want to set `"indent_guide_options": ["draw_normal", "draw_active"]` in the settings to highlight currently active guide.

## Vim

![SaltStack plugin for Vim](https://salt.tips/text-editor-plugins-for-salt-states-and-yaml-jinja/salt-vim.png)

You need both [salt-vim](https://github.com/saltstack/salt-vim.git) and [vim-jinja2-syntax](https://github.com/Glench/Vim-Jinja2-Syntax.git).

#### Features

- Syntax highlighting for `*.sls` files and `Saltfile`
- Syntax highlighting for `*.jinja2`, `*.j2` and `*.jinja` files
- Proper indentation settings
- `Space` key will try to fold/unfold an area
- A visually selected block might be indented and unindented with `<` and `>`

If you are using Vim 8 or higher, you may skip the Pathogen/Vundle route and install the plugins directly:

```
mkdir -p ~/.vim/pack/plugins/start
cd !$
git clone https://github.com/saltstack/salt-vim.git salt.vim
git clone https://github.com/Glench/Vim-Jinja2-Syntax.git jinja2.vim
```

Then add the following lines to your `.vimrc`:

```
syntax on
set nocompatible
set modeline
filetype plugin indent on
let g:sls_use_jinja_syntax = 1
```

You might also consider [vim-indentguides](https://github.com/thaerkh/vim-indentguides), [vim-indent-guides](https://github.com/nathanaelkane/vim-indent-guides) or [indentLine](https://github.com/Yggdroot/indentLine). Some folks use [crosshair highlighting](http://vim.wikia.com/wiki/Highlight_current_line).

## Visual Studio Code

![SaltStack extension for Visual Studio Code](https://salt.tips/text-editor-plugins-for-salt-states-and-yaml-jinja/salt-vscode.png)

The VSCode extension for SaltStack is available on the [Marketplace](https://marketplace.visualstudio.com/items?itemName=korekontrol.saltstack). To install it click `File -> Preferences -> Extensions`, then search for `saltstack` and click install. The source code is available on [GitHub](https://github.com/korekontrol/vscode-saltstack)

#### Features

- Has syntax highlighting for `*.sls` files (understands YAML+Jinja combo)
- Autocompletion of Jinja brackets
- Folding of indented lines in YAML
- Also supports `*.j2` and `*.jinja` extensions

If you get annoyed by extra closing bracket added by autocompletion `{%%}}`, add the following snippet to your `settings.json` file (`File -> Preferences -> Settings`, then press the `{}` icon to open User Settings):

```json
"[sls]": { "editor.autoClosingBrackets": "never" }
```

## Final tips

#### For teams

If you have a team of engineers who regularly contribute to a common Salt state tree, it is essential to establish some YAML/Jinja style conventions.

You could add the following boilerplate to each state file, but it is easy to forget and requires some discipline:

```
# -*- coding: utf-8; mode: salt; -*-
# vim: ft=sls
```

Alternatively, you could ask engineers to set up their editors properly. Or you can adopt [http://editorconfig.org/](http://editorconfig.org/) - just create a `.editorconfig` in your project root, and any compatible editor will automatically pick up your coding convention.

Also, it makes sense to add `.jinja` or `.j2` suffix to all config templates managed by Salt, to help most editors recognize the syntax.

#### YAML docs

- [YAML Cheatsheet](https://kapeli.com/cheat_sheets/YAML.docset/Contents/Resources/Documents/index) (also could be used with [Dash](https://kapeli.com/dash))
- [The YAML Format](https://symfony.com/doc/current/components/yaml/yaml_format.html) (from the Symfony docs)
- [YAML Multiline](https://yaml-multiline.info/) (a nice cheatsheet for YAML multiline strings)
- [Understanding YAML](https://docs.saltstack.com/en/latest/topics/yaml/) (from the Salt docs)
- [YAML Idiosyncrasies](https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html) (from the Salt docs)
- [YAML Specification](http://yaml.org/spec/1.2/spec.html) (authoritative and comprehensive, but not so easy to read)

#### Jinja docs

- [Jinja Template Designer Documentation](http://jinja.pocoo.org/docs/templates/) (please choose the appropriate Jinja version to match the one installed in your Salt environment)
- [Understanding Jinja](https://docs.saltstack.com/en/latest/topics/jinja/index.html) (from the Salt docs)

#### Online YAML parsers/linters

These could be helpful if you don’t want to or can’t use any editor plugins:

- [https://github.com/Inveracity/jinjabread](https://github.com/Inveracity/jinjabread) (made specifically for Salt)
- [http://yaml-online-parser.appspot.com/](http://yaml-online-parser.appspot.com/)
- [https://www.json2yaml.com/](https://www.json2yaml.com/)
- [http://www.yamllint.com/](http://www.yamllint.com/)

Also, YAML is a [superset of JSON](http://yaml.org/spec/1.2/spec.html#id2759572), so you could just use square brackets for lists and curly ones for dictionaries:

```
/etc/http/conf/http.conf:
  file.managed:
    - source: salt://apache/http.conf
    - mode: 644
    - template: jinja
    - context: { custom_var: "override" }
    - defaults: { custom_var: "default value", other_var: 123 }
```

* * *

If you want to be notified about tips like this one, you can subscribe to the [mailing list](https://tips.us8.list-manage.com/subscribe?u=79863cb6907503346da4ed704&id=9de0347807).

Also, you can follow me on [<svg xmlns="http://www.w3.org/2000/svg" aria-label="Twitter" role="img" width="20" height="20" viewbox="0 20 512 532"><path fill="#000" d="M437 152a72 72 0 0 1-40 12 72 72 0 0 0 32-40 72 72 0 0 1-45 17 72 72 0 0 0-122 65 200 200 0 0 1-145-74 72 72 0 0 0 22 94 72 72 0 0 1-32-7 72 72 0 0 0 56 69 72 72 0 0 1-32 1 72 72 0 0 0 67 50 200 200 0 0 1-105 29 200 200 0 0 0 309-179 200 200 0 0 0 35-37"></path></svg>Twitter](https://twitter.com/SaltTips) where I periodically post things like this:

[![SaltTips tweet](https://salt.tips/text-editor-plugins-for-salt-states-and-yaml-jinja/tweet-example.png) ](https://twitter.com/SaltTips)