Package Specification
In this document, we are going to discuss the format specification for Espanso packages and repositories. If you are trying to create your first package, we suggest reading the Creating a Package section first, as that contains the basic information you'll need for most use-cases.
In the first part, we'll go through the structure of an Espanso package, starting from a top level view with the included files, all the way down to the actual content. Then, the second part covers the structure a typical package repository.
Packages format
As we first introduced in the Creating a package section, a package is a combination of YAML match files with some metadata.
The most basic package MUST contain these 3 files:
- A
package.yml
file, containing snippets you want to share. - A
_manifest.yml
file, containing the metadata of the package. This includes the package's name, author and version, among other things. - A
README.md
file, containing a description of the package, written using Markdown syntax.
Optionally, a package can also contain:
- A
LICENSE
file, if you want to publish your package under a different license than the default HUB one (MIT). - Any number of additional YAML files, which can be used to split the matches across multiple files to make them more manageable.
- Scripts called by your snippets
In the following sections, we'll examine them in detail, but first we'll need to briefly discuss package names.
Package name rules
A package name can only contain lowercase letters, numbers and the hypen symbol -
.
For example, the following are valid names:
my-nice-package1234
great-package
While these are NOT valid names:
My Package
my_package
nice@package
The package.yml
file
The package.yml
file is the entry-point of the package.
It contains the main matches (aka snippets) for the current package, and its format is equivalent to the $CONFIG/match/base.yml
file, as explained here.
As with regular match files, it can contain matches, global variables and import rules.
A typical package.yml
file might look like the following:
matches:
- trigger: ":hello"
replace: "Hello from package"
- trigger: ":another"
replace: "Another snippet from the example package"
The _manifest.yml
file
The _manifest.yml
file contains the package metadata, including the package name, author and version.
This file is encoded in the YAML syntax.
A _manifest.yml
MUST contain these fields:
name:
should be the name of your package. It must be equal to the directory name containing the package.title:
is the "read-friendly" version of your package name. This can contain all string characters, but it should be relatively short.description:
should contain a short description of your package.version:
contains the version of your package. We suggest to start at0.1.0
for new packages. This must match the version number in the package path.author:
contains the author name.tags:
followed by a sequence of keywords to help users find your work - see Espanso Hub for examples.homepage:
a link to your package's homepage. This could be a website, a documentation page or a Git repository.
Note about package versions
As we discussed earlier, the _manifest.yml
file also contains the package version:
. This package version should follow the standard MAJOR.MINOR.PATCH
format.
When installing or updating a package, Espanso uses the version to determine if an update should be performed or not. For this reason, we suggest increasing the version after an update is made to the package.
If you don't to this, you'll need to use the --force
option when updating.
The README.md
file
The README.md
file contains a description of the package, formatted with the Markdown syntax.
The main purpose of this file is to describe and document the package. For example, if your package depends on an external script or command, this is a good place to mention it. This file will appear in Espanso Hub if accepted for the espanso/hub repository.
Repository format
TODO
- Repository Format
- Multiple versions format
- Flat format