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:

package.yml

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 at 0.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.

Optionally, the manifest can also contain:

• 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