Skip to main content

Contributing: Adding Devices

Create device folder and markdown file​

  1. To add a new device create a new folder named after your device under the src/docs/devices directory in the GitHub Repository. In that folder, create a markdown (.md) file named index.md with the content. Please avoid using underscores or spaces in the filenames and use hypens instead as this makes for easier to understand the URLs generated when the site is built. When using the Add file -> Create new file button in the Devices folder or by following this link, Github will automatically create a fork of the repository and a new branch for your changes. Just type the device name for the folder followed by a /index.md (including the slash).

    Fork on GitHub

  2. Once you have written your file commit your changes and raise a pull request on GitHub. A guide for creating a pull request from a fork can be found in the GitHub documentation if you are unsure.

YAML Front Matter​

Each .md file created needs to contain front matter in order for the page to be generated. Details of the front matter required (and optional) is detailed below:

---
title: Sonoff S20
date-published: 2019-10-11
type: plug
standard: uk, us
---
FieldDescriptionAllowable OptionsRequired?
titleDevice TitleYes
date-publishedDate PublishedFormatting: YYYY-MM-DD HH:MM:SS +/-TTTT (Time and Timezone offset are optional)Yes
typeType of Deviceplug, light, switch, dimmer , relay, sensor, miscYes
standardElectrical standard countryuk, us, eu, au, in, globalYes
boardType of board used in productesp8266, esp32, rp2040, bk72xx, rtl87xxNo (but required to show on Boards page)
project-urlURL for product or GitHub. Points to working Yaml file or page where yaml file is easily accessibleNo
made-for-esphomeHas the manufacturer certified the device for ESPHomeTrue, FalseNo
difficultyDifficulty rating1: Comes with ESPHome, 2: Plug-n-flash, 3: Disassembly required, 4: Soldering required, 5: Chip needs replacementNo

Images​

To add images to your files do the following:

  1. Add the images to your newly created device folder in /src/docs/devices
  2. Add the images to your folder using the appropriate markdown syntax:
![alt text](your-image.jpg "Image Hover Text")