# yaml-mode is a small Emacs major mode that nobody owns any more > yoshiki/yaml-mode is a single-file Emacs Lisp major mode for editing YAML, GPL-3.0 licensed, with a Makefile, ERT tests and a stable install path. Its own README opens by telling readers it needs a new maintainer, which is the most important fact about it. **yoshiki/yaml-mode** — The emacs major mode for editing files in the YAML data serialization format. - Repository: https://github.com/yoshiki/yaml-mode - Stars: 522 · Forks: 131 - Language: Emacs Lisp - License: GPL-3.0 - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/yoshiki-yaml-mode ## The README starts with a recruitment notice The first thing in the README is not a description of the software, it is an appeal. The author writes that they have not used Emacs and this library for a long time, and that they are recruiting maintainers or collaborators for all yaml-mode users, with a request to get in touch. That framing is unusual and it changes how you should read everything else in the file. The author is Yoshiki Kurihara, and the copyright line dates the work to 2010 by the Free Software Foundation, Inc. The mode is described as a simple major mode to edit YAML files for Emacs, and the requirement is Emacs 24.3. What you are looking at is a single `.el` file, not a package. The top-level entries are `yaml-mode.el`, a `Makefile`, a `Changes` file, a `LICENSE.txt`, a `README`, a `.dir-locals.el`, a `test/` directory and a `test-files/` directory, plus `.github/` and `.gitignore`. So the honest characterisation is: a small, complete, working piece of Emacs infrastructure whose upstream is asking for someone to take it on. That is a different proposition from a package you install and forget, and it is the main thing to weigh before you adopt it. ## Installation is a Makefile with a PREFIX you can change The install path is conventional Unix, and the Makefile is small enough to read in one screen. The version is 0.0.15, the Emacs binary is `emacs`, and the default prefix is `/usr/local`. The README gives the two commands: ```bash % make % make install ``` The `make` target byte-compiles the source into `yaml-mode.elc` using a batch Emacs run with the install library directory on the load path: ```makefile bytecompile: $(EMACS) $(FLAGS) $(SRC) install: bytecompile $(INSTALL) yaml-mode.elc $(INSTALLLIBDIR) $(INSTALL) yaml-mode.el $(INSTALLLIBDIR) ``` The `INSTALL` variable is `/usr/bin/install -c -m 444`, so the installed files are read-only, which is why the `uninstall` target uses `rm` rather than `rm -f` and why a plain `make install` into `/usr/local` usually needs administrator rights. There is a documented alternative for a per-user install, which is the route most people on a managed machine want: ```bash % make PREFIX=/your/home/dir % make install PREFIX=/your/home/dir ``` With that prefix the files land in `$(PREFIX)/share/emacs/site-lisp`, which you then add to your `load-path`. There is also a `tardist` target that assembles a `yaml-mode-0.0.15` directory and tars it, which is what a packager would use, and a `clean` target that removes the byte-compiled output, the backup files and the tarball. The `FLAGS` variable is `-batch -L $(INSTALLLIBDIR) -q -f batch-byte-compile`, so byte compilation happens with a quiet batch Emacs that loads the installed site-lisp first, which lets the compiler resolve any macros available there. ## Hooking .yml files and the deliberate refusal to bind ENTER Making the mode load for YAML files takes two lines in your Emacs configuration. The first requires the library, the second adds an entry to `auto-mode-alist`: ```elisp (require 'yaml-mode) (add-to-list 'auto-mode-alist '("\\.yml\\'" . yaml-mode)) ``` Note that the pattern only matches `.yml`, not `.yaml`. The README's synopsis shows only the `.yml` case, and there is no separate example for the three-letter extension, so if your project uses `.yaml` files you have to add that pattern yourself. The second configuration detail is the one that trips up new users, and the README explains it by comparison with python-mode. Unlike python-mode, this mode follows the Emacs convention of not binding the ENTER key to `newline-and-indent`. If you want that behaviour, you add the key definition to `yaml-mode-hook`: ```elisp (add-hook 'yaml-mode-hook '(lambda () (define-key yaml-mode-map "\C-m" 'newline-and-indent))) ``` The reasoning behind the convention is that in YAML, indentation is significant and is determined by the structure of the document rather than by the previous line, so a mode that re-indents on newline can silently change the meaning of a block. Binding ENTER to a plain newline leaves the indentation to you. The consequence is that the first thing most users do is undo the convention by adding the hook above. That is fine, but it means the mode's out-of-the-box behaviour is deliberately not what a python-mode user expects, and you should decide which you want before you start editing files. ## Tests exist, and they run under ERT in batch mode The repository has a `test/` directory and a `test-files/` directory, which is more than most single-file Emacs modes of this age manage. The Makefile has a `test` target that runs them: ```makefile test: $(EMACS) -Q -batch -L . \ -l test/yaml-mode-test.el \ -f ert-run-tests-batch-and-exit ``` Three details in that command matter. `-Q` skips the user init file, so the tests run against a clean Emacs with no personal configuration. `-batch -L .` adds the repository root to the load path, so `yaml-mode.el` is found from the checkout rather than from an installed copy. And `ert-run-tests-batch-and-exit` is the standard ERT runner, which exits with a non-zero status when a test fails, so the target works in CI. That is the right shape for an Emacs package: a test target that a CI job can call. The presence of `.github/` in the top-level entries suggests a workflow exists, although the README does not describe what the CI does beyond the badges shown for the upstream Nullgram project, which belong to a different repository. The `test-files/` directory is the other half. For a mode that manipulates indentation and comments, the interesting cases are in the fixtures rather than in the assertions: a YAML document with the awkward constructs that break naive indentation logic is what you want to see, and having them checked in as files is how you let a change to the indentation rules be compared against a known-good input. ## What the mode actually gives you, and what it does not The README's DESCRIPTION section is two words long: yaml-mode is a major mode for Emacs. There is no feature list, no list of supported YAML constructs, no changelog of indentation behaviour, and no documentation of the key bindings other than the ENTER caveat. That thinness is the practical limit of what you can evaluate from the documentation. You know the file is a major mode, you know how to install it, you know how to attach it to `.yml` files, and you know the mode is self-contained in one source file. You do not know from the README which YAML features are handled well, whether tabs are supported, how comments are reflowed, or how the mode behaves with the block scalar syntax that makes YAML indentation-sensitive. The `Changes` file is where the history lives, and the Makefile version string says 0.0.15, which tells you this is a long-lived project rather than a single afternoon's experiment. Reading `Changes` before you install is the cheapest way to find out whether the recent entries are about behaviour you depend on, or about packaging and compatibility housekeeping. There is also a `.dir-locals.el` in the repository. That file is what lets a directory carry its own local variables when you visit it, and for a mode that operates on a particular file format it is the conventional place to declare that files in the directory are YAML. ## The alternative: a full YAML package, or the mode you already have The realistic alternative to a single-file mode is a maintained YAML package with language-server support, which is a different class of tool. The difference in approach is that such a package gives you completion, schema validation and inline diagnostics driven by an external language server, whereas yaml-mode gives you text editing behaviour only: indentation, and whatever key handling the file implements. That difference cuts both ways. If you edit YAML in a large project with a schema, a text mode will not tell you that a key is wrong or that an anchor is undefined, and no amount of configuration will change that. If you edit YAML to write a config file for one tool, to sketch a Kubernetes manifest, or to read a CI config, a text mode is enough, and the schema server adds a process, a download and a startup cost for a file with six keys. The second alternative is closer to home for Emacs users: modern Emacs has YAML support in its own `yaml-mode`, which ships with the editor. The difference there is the same in kind. The built-in mode is maintained with the editor and has a larger user base, but it is generic; a focused third-party mode can be tuned for the particular indentation conventions a project uses. The practical question is not which is more capable. It is whether you want a dependency you do not maintain. A single `.el` file that installs with `make` and has ERT tests is something you can read end to end in an afternoon and keep working. That is the argument for it, and the recruitment notice in the README is the argument against. ## Conclusion Adopt yaml-mode if you edit YAML in Emacs and want indentation, comment handling and a .yml auto-mode hook without configuring a heavier package. Do not adopt it if you need YAML language-server features, schema validation or a maintained upstream, because the README states plainly that the author has not used Emacs or the library for a long time and is recruiting maintainers. Before you install it, check that the indentation matches your project's YAML style, because the mode deliberately does not bind ENTER to `newline-and-indent` the way python-mode does, and read `Changes` to see how far the mode has moved since version 0.0.15. ## FAQ ### How do I install yaml-mode for Emacs? The README gives two commands, `make` and `make install`, which byte-compile `yaml-mode.el` and install it into `$(PREFIX)/share/emacs/site-lisp`. For a per-user install you pass a prefix, with `make PREFIX=/your/home/dir` followed by `make install PREFIX=/your/home/dir`, and add that directory to your `load-path`. ### How do I make Emacs open .yml files in yaml-mode? Add `(require 'yaml-mode)` and `(add-to-list 'auto-mode-alist '("\\.yml\\'" . yaml-mode))` to your Emacs configuration, as the synopsis shows. The example pattern covers the .yml extension only, so .yaml files need their own entry. ### Why does yaml-mode not indent automatically when I press ENTER? The mode follows the Emacs convention of not binding the ENTER key to `newline-and-indent`, unlike python-mode, and the README suggests adding a key definition to `yaml-mode-hook` if you want that behaviour back. ### What does yaml-mode require and how is it tested? The requirement is Emacs 24.3. The Makefile has a test target that runs the ERT suite in a batch Emacs with `-Q` so no personal configuration is loaded, and the repository carries a `test/` directory plus a `test-files/` directory of fixtures. ### Is yaml-mode still maintained? The README opens by stating that the author has not used Emacs and the library for a long time and is recruiting maintainers or collaborators. The repository is not archived, and the last push was on 2026-08-30. ## Sources - [Issues](https://github.com/yoshiki/yaml-mode/issues) - [License: GPL-3.0](https://github.com/yoshiki/yaml-mode/blob/master/LICENSE) - [README](https://github.com/yoshiki/yaml-mode/blob/master/README.md) - [yoshiki/yaml-mode on GitHub](https://github.com/yoshiki/yaml-mode) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yoshiki-yaml-mode