ADDON.md is your addon’s store page. It sits next to manifest.json in the addon’s directory, and the store shows it as the addon’s page: a banner, a gallery of images and videos, and a Markdown body.
The page is display only. The manifest stays the source of truth for everything Unbound reads: the name, the description, the authors, and the version. The store takes the page title and summary from the manifest, so ADDON.md never repeats them.
Addon directory
Frontmatter
The page starts with YAML frontmatter between two--- lines. Unbound parses it with the yaml package. A key that appears twice, or a key not listed below, fails the build. title and description also fail the build, because those come from the manifest.
string
required
The image across the top of the page. It must be exactly 3:1 and at least 1200x400 pixels.
PageMedia[]
default:"[]"
The gallery, shown in the order you list it. Up to 20 entries. Each entry is an image or a video, and must be between 9:16 (portrait) and 21:9 (ultrawide).
image or video, never both. Only a video entry takes a poster.
Body
After the frontmatter, write standard Markdown. Do not start with a# heading: the manifest’s name is already the page title. Start with ## or with a paragraph.
To show an image or a video in the body, use image syntax with a path under media/. The extension decides whether the file renders as an image or a video.
Media
Every banner, gallery entry, poster, and body image is a file in your repository, inside the addon’smedia/ folder. Links to images on other sites fail the build.
- A path is relative to the addon’s directory and starts with
media/. Subfolders are allowed:media/screens/settings.png. - A file or folder name uses letters, digits,
_,-, and., and does not start with a.. A path has at most 200 characters. - Extensions are case-insensitive.
media/SHOT.PNGis an image. - A single file can be at most 10 MB. All media in one addon together can be at most 50 MB.
What ubd build does with the page
ubd build reads ADDON.md, opens every media file it references, and measures each one: its width, its height, its size in bytes, the length of a video, and a small placeholder the store shows while the file loads. It writes the result to page.json in the build output, next to the bundle and the built manifest.json. Commit page.json with the bundle. When you publish, the server checks the sizes and formats again against the files in your repository.
Measuring a video needs FFmpeg: ffmpeg and ffprobe must be on your PATH. Images need nothing extra. To change the size limits for a build, set ADDON_MEDIA_MAX_BYTES (one file) or ADDON_MEDIA_TOTAL_MAX_BYTES (all media) in bytes.
The build fails when the page has any of these problems:
- The frontmatter is not valid YAML, has a key twice, or has a key not listed under Frontmatter.
- The
banneris missing, is not 3:1, or is smaller than 1200x400. - A gallery entry is outside 9:16 to 21:9, or has no
alt. - A media path is outside
media/, points at another site, or has an extension not listed under Media. - A referenced media file does not exist, or is larger than the size limits.
- A media file’s contents do not match its extension, or a video uses a codec other than H.264, HEVC, or AV1 (
.mp4) or VP8, VP9, or AV1 (.webm). - The body starts with a
#heading. - The body contains a table. Use a list instead.
The store still shows tables on pages published before this rule. New builds reject them.
Example
ADDON.md
ubd build writes a page.json like this one. Your numbers depend on your files.
page.json