diff --git a/source/_includes/asides/developers_navigation.html b/source/_includes/asides/developers_navigation.html index 34f1de46476..0f42206817a 100644 --- a/source/_includes/asides/developers_navigation.html +++ b/source/_includes/asides/developers_navigation.html @@ -95,6 +95,7 @@
  • {% active_link /developers/hassio/addon_communication/ Communication %}
  • {% active_link /developers/hassio/addon_testing/ Local Testing %}
  • {% active_link /developers/hassio/addon_publishing/ Publishing %}
    • +
  • {% active_link /developers/hassio/addon_presentation/ Presentation %}
  • {% active_link /developers/hassio/addon_repository/ Repositories %}
    • diff --git a/source/developers/hassio/addon_config.markdown b/source/developers/hassio/addon_config.markdown index 031dbabb3fc..005c8a0cd83 100644 --- a/source/developers/hassio/addon_config.markdown +++ b/source/developers/hassio/addon_config.markdown @@ -12,10 +12,15 @@ redirect_from: /hassio/addon_config/ Each add-on is stored in a folder. The file structure looks like this: -``` +```text addon_name/ - Dockerfile + build.json + CHANGELOG.md config.json + Dockerfile + icon.png + logo.png + README.md run.sh ``` diff --git a/source/developers/hassio/addon_development.markdown b/source/developers/hassio/addon_development.markdown index 40680cd1415..ec1f3f96748 100644 --- a/source/developers/hassio/addon_development.markdown +++ b/source/developers/hassio/addon_development.markdown @@ -14,11 +14,10 @@ Add-ons for Hass.io allow the user to extend the functionality around Home Assis Under the hood, add-ons are Docker images published in [Docker Hub](https://hub.docker.com/). Developers can create [GitHub](https://github.com) repositories that contain multiple references to add-ons for easy sharing with the community. -
      -
    1. Tutorial: Making your first add-on
      2. -
    2. Configuration
      3. -
    3. Communication
      4. -
    4. Local Testing
      5. -
    5. Publishing
      6. -
    6. Repositories
      7. -
    +1. [Tutorial: Making your first add-on](/developers/hassio/addon_tutorial/) +1. [Configuration](/developers/hassio/addon_config/) +1. [Communication](/developers/hassio/addon_communication/) +1. [Local Testing](/developers/hassio/addon_testing/) +1. [Publishing](/developers/hassio/addon_publishing/) +1. [Presentation](/developers/hassio/addon_presentation/) +1. [Repositories](/developers/hassio/addon_repository/) diff --git a/source/developers/hassio/addon_presentation.markdown b/source/developers/hassio/addon_presentation.markdown new file mode 100644 index 00000000000..413dd0489dc --- /dev/null +++ b/source/developers/hassio/addon_presentation.markdown @@ -0,0 +1,49 @@ +--- +layout: page +title: "Presenting your add-on" +description: "Details on how to present your Hass.io add-on." +date: 2018-01-24 22:15 +sidebar: true +comments: false +sharing: true +footer: true +--- + +If you decide to share your add-on to the public, paying attention to details is recommended. Of course, your add-on should have a proper name and description, but Hass.io also gives you some other tools to present your add-on even nicer. + +## {% linkable_title Adding documentation %} + +Good documentation helps the consumer of your add-on to understand its usage, explains configuration options, points users in the right direction in the case they have questions or issues, and contains the license under which the add-on was published. + +This file containing the documentation is usually referred to as the "README", which is generally published as the `README.md` file. + +Take a look at other projects for inspiration. For example, see the `README.md` of the [Community Hass.io Add-ons: Homebridge](https://github.com/hassio-addons/addon-homebridge/blob/master/README.md) add-on. + +In future versions of Hass.io, the `README.md` file will be displayed in the Home Assistant frontend. + +## {% linkable_title Add-on icon & logo %} + +A picture is worth a thousand words. Therefore, your add-on can be improved by adding a proper image icon and logo. Those images are used when showing your add-on in the Home Assistant Hass.io panel and which will significantly improve the visual representation of your add-on. + +Requirements for the logo of your add-on: + +- The logo must be in the Portable Network Graphics format (`.png`). +- The filename must be `logo.png`. +- It is recommended to keep the logo size around 250x100px. You may choose to use a different size or aspect ratio as you seem fit for your add-on. + +Requirements for the icon of your add-on: + +- The icon must be in the Portable Network Graphics format (`.png`). +- The filename must be `icon.png`. +- The aspect ratio of the icon must be 1x1 (square). +- It is recommended to use an icon size of 128x128px. + +## {% linkable_title Keeping a changelog %} + +It is likely you are going to release newer versions of your add-on in the future. In case that happens, the users of your add-on would see an upgrade notice and probably want to know what changes were made in the latest version. + +A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of your add-on and is generally published as the `CHANGELOG.md` file. + +If you are in need of a guide on keeping a changelog, we would recommend checking the [keep a changelog](http://keepachangelog.com) website. They have developed a standard that is used by many opensource projects around the world. + +In future versions of Hass.io, the `CHANGELOG.md` file will be displayed in the Home Assistant frontend. diff --git a/source/developers/hassio/addon_repository.markdown b/source/developers/hassio/addon_repository.markdown index 3ad7da57fe1..645fb1cf819 100644 --- a/source/developers/hassio/addon_repository.markdown +++ b/source/developers/hassio/addon_repository.markdown @@ -10,7 +10,7 @@ footer: true redirect_from: /hassio/addon_repository/ --- -An Add-on repository can contain one or more add-ons. Each add-on is stored in it's own unique folder. To be indentified as a repository, the repository must contain a configuration file. +An add-on repository can contain one or more add-ons. Each add-on is stored in it's own unique folder. To be indentified as a repository, the repository must contain a configuration file. Check the [Example add-on repository](https://github.com/home-assistant/hassio-addons-example) for further details.