Presentation and store assets

How an add-on looks in the store and in the UI is driven entirely by files with fixed names in the add-on directory, plus a few config.yaml keys. None of the filenames are configurable.

Icon and logo

File	Where it appears	Shape
icon.png	Store listings, sidebar, dialogs	Square PNG
logo.png	Header of the add-on's page	Wide PNG

Conventions from the official store:

• icon.png is a square PNG. The flagship add-ons ship 128 × 128 RGBA icons (samba, ssh); keep it square and legible at small sizes.
• logo.png is a wide, roughly banner-shaped PNG — real examples are 283 × 167 (samba) and 520 × 155 (ssh). It sits full-width above the add-on description, so favor a horizontal lockup rather than a scaled-up icon.

Both files are read from the add-on root by the Supervisor (icon.png, logo.png — exact names) and served to the frontend without authentication so the store can render listings, so do not embed anything sensitive in them.

Do not confuse these with panel_icon: in config.yaml — that is a Material Design Icons name (default mdi:puzzle) used for the sidebar entry of ingress-enabled add-ons, not an image file.

README.md — the long description

The add-on's README.md is read from the store source and used as its long description in the store UI. Keep it short and store-oriented: what the add-on does and why a user would install it. Detailed instructions belong in DOCS.md.

DOCS.md — the documentation tab

DOCS.md (exact name, read from the add-on root) is rendered as the add-on's Documentation tab. bashio::addon.has_documentation / bashio::addon.documentation expose it via the API as well.

Conventions used across the official store (see samba/DOCS.md):

• Title: # ApexOS App: <Name> — the UI calls add-ons "Apps", and the docs follow that user-facing vocabulary.
• An Installation section with the store click-path (Settings > Apps > Install app).
• A How to use section with numbered first-run steps.
• A Configuration section that shows a complete example option block as YAML and then documents each option (matching your schema:), including which options are required.
• Tables for enumerable things (shares, directories, ports).
• Write for end users: no build instructions, no source-tree paths.

CHANGELOG.md — the update notes

CHANGELOG.md (exact name) is shown to users when an update is available. Store convention:

# Changelog

## 12.8.1

- Initial ApexOS port of the Samba share add-on (upstream 12.8.1).
- Config share serves the ApexOS configuration mount (`/apexos`).
- Builds locally from the ApexOS add-on base image.

One ## <version> section per release, newest first, bullet points per change. The top section should always match the version: in config.yaml — users read it as "what am I about to install".

translations/ — option labels

The configuration UI renders your options/schema as a form. Without translations, users see raw keys. Provide translations/<language>.yaml files (the language code is taken from the filename, e.g. en.yaml); each file supports two top-level blocks:

configuration:
  username:
    name: Username
    description: >-
      The username you would like to use to authenticate with the Samba server.
  password:
    name: Password
    description: >-
      The password that goes with the username configured for authentication.
network:
  22/tcp: SSH port

• configuration.<option>.name — the field label (required per entry).
• configuration.<option>.description — help text under the field.
• Nested option groups are supported via nested fields.
• network.<port> — labels for port fields (alternatively ports_description: in config.yaml serves the same purpose without translation support).

Files that fail to parse are skipped with a logged warning; unknown keys are dropped. The official add-ons currently ship en.yaml.

config.yaml keys that affect presentation

Key	Effect
name	Display name everywhere.
description	One-liner in store listings.
url	"Visit homepage" link (also stamped into the image as the io.apexos.url label).
stage	experimental/deprecated flags in the store; default stable.
panel_icon, panel_title, panel_admin	Sidebar panel of ingress add-ons — icon name (default mdi:puzzle), title (defaults to the add-on name; the ssh add-on shortens it to Terminal), and whether it is admin-only (default true).
webui	Enables the "Open Web UI" button with the templated URL.
ports_description	Untranslated labels for the port configuration fields.

Checklist

Per release, an add-on directory should present:

• icon.png (square) and logo.png (wide) — exact filenames
• README.md — short store description
• DOCS.md — full user manual, options documented against schema:
• CHANGELOG.md — ## <version> section matching config.yaml
• translations/en.yaml — name/description for every option
• description, url, and (for ingress) panel_* set in config.yaml