vim-registry(5)

💖 vim-registry 💖

okay bestie, welcome to vim-registry(5) — a section 5 file from the vim addons manual, and it's literally all about the syntax for vim-addons registry files. it's giving config-file lore and i'm obsessed. let's get into it 🫶

✨ SYNOPSIS ✨

PACKAGE-NAME.yaml

🌸 DESCRIPTION 🌸

so a registry file is a multi-document YAML file — meaning it can be made up of several different YAML documents, all chillin' in the same file, separated by --- lines. and each one of those YAML documents is a registry entry, aka the info that describes a single addon. one doc, one addon. periodt. 💅

ideally, the registry directory has one file per package that ships addons, and the filename follows the convention PACKAGE-NAME.yaml. so a single package can contribute to the registry with multiple entries described inside one single YAML file. no cap.

for example, the vim-scripts package should ship a single /usr/share/vim/registry/vim-scripts.yaml file, and that file contains one YAML document per shipped addon. the first lines of such a file can look like this:

addon: alternate
description: "alternate pairing files (e.g. .c/.h) with short ex-commands"
basedir: /usr/share/vim-scripts/
disabledby: "let loaded_alternateFile = 1"
files:
  - plugin/a.vim
  - doc/alternate.txt
---
addon: whatdomain
description: "query the meaning of a Top Level Domain"
basedir: /usr/share/vim-scripts/
disabledby: "let loaded_whatdomain = 1"
files:
  - plugin/whatdomain.vim
---

each registry entry may contain the following fields, and they have to be typeset according to the YAML specification. here's the field-by-field vibe check 👇

• addon (Required) — the name of the addon.
• description (Required) — a human understandable textual description of the addon.
• files (Required) — the list of the files which compose the addon and are required to be present in a component of the Vim runtime path for the addon to be enabled. each file is specified relative to a component of the Vim runtime path.
• basedir (Optional) — the directory where the files shipped by the addon reside on the filesystem (i.e., where the symlinks of the user/sysadm should point to). the default is /usr/share/vim/addons.
• disabledby (Optional) — a Vim script command that can be used (usually by adding it to ~/.vimrc) to prevent the addon from being used even when it's installed. the intended usage of this field is to "blacklist" an undesired addon whose files are available — and hence automatically loaded by Vim — in a component of the Vim runtime path.

ok so quick heads up bestie: addon, description and files are Required, no skipping them. basedir and disabledby are the optional lil bonus fields. and remember, everything gets typeset per the YAML spec. iykyk 💜

👑 AUTHOR 👑

James Vega <jamessan@debian.org>

🦋 SEE ALSO 🦋

vim-addons(1), YAML specification

💜 COPYRIGHT 💜

Copyright (C) 2010 James Vega

This program is free software, you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

and that's the whole page, bestie!! 🎀 big thanks to the Debian Project for this one — it's dated January 2010 and it's the vim-registry(5) page, main character of registry syntax fr fr. go forth and write your YAML docs separated by --- like the icon you are ✨🌸💖