TODO: this section is under construction
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.
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:
package.ymlfile, containing the snippets you want to share.
_manifest.ymlfile, containing the metadata of the package. This includes the package's name, author and version, among other things.
README.mdfile, containing a description of the package, written using the Markdown syntax.
Optionally, a package can also contain:
LICENSEfile, 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.
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:
While these are NOT valid names:
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.
package.yml file might look like the following:
- trigger: ":hello"
replace: "Hello from package"
- trigger: ":another"
replace: "Another snippet from the example package"
_manifest.yml file contains the package metadata, including the
package name, author and version.
This file is encoded in the YAML syntax.
_manifest.yml MUST contain these fields:
nameshould be the name of your package. It must be equal to the directory name containing the package.
titleis the "read friendly" version of your package name. This can contain all string characters, but it should be relatively short.
descriptionshould contain a short description of your package.
versioncontains the version of your package. We suggest to keep it at
0.1.0for new packages.
authorcontains the author name.
Optionally, the manifest can also contain these fields:
homepageshould be the 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
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.
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.
- Repository Format
- Multiple versions format
- Flat format