Contributing: Adding Devices

Create device folder and markdown file

Step 1: Fork the repository

Go to github.com/esphome/esphome-devices/fork and click Create fork. This gives you your own copy of the repo at github.com/<your-username>/esphome-devices.

Once your fork is created, come back to this page to continue.

Step 2: Create the device file

The fastest way is to use the link generator below — fill in the link to your fork (or just your GitHub username) and the device name, and it will open GitHub's new file page with the filename and front matter pre-filled.

Your fork URL or GitHub usernameDevice name

Open pre-filled new file page on GitHub

Or create the file manually

Follow these steps in your fork:

1. Open the devices folder. Navigate to src/docs/devices in your fork.

2. Click Add file → Create new file.

3. Name the file. Start by typing your device's folder name — e.g. some-new-device:

   

   Then type a / (forward slash) after the name. GitHub will automatically turn what you typed into a folder and move the cursor into a new filename field inside it. Finish by typing index.md:

   

   Use hyphens (-) in folder names instead of underscores or spaces. This keeps the generated URLs clean and readable.

Step 3: Write the content

The file needs a YAML front matter block at the top, followed by the device's documentation in Markdown.

If you used the link generator in Step 2, the filename and a starter template are already filled in for you — but you still need to fill in the empty front matter fields (type, standard, and optionally board) and write the documentation in the body.

If you created the file manually, you'll need to add the entire front matter block plus the documentation yourself.

See the YAML front matter section below for the list of valid options for each field.

Step 4: Commit your changes

Click Commit changes... at the top right. A dialog will appear:

• Leave the default commit message or write your own.
• Important: select Create a new branch for this commit and start a pull request, and give the branch a short name like some-new-device. Do not commit directly to main — committing to main in your fork makes it harder to open clean pull requests later.
• Click Propose changes.

Step 5: Open the pull request

GitHub will take you to the pull request page automatically. Check that the base repository is esphome/esphome-devices and the base branch is main, then click Create pull request to submit it.

If the base repository is set to your own fork instead of esphome/esphome-devices, click the compare across forks link near the top of the page. That will reveal the base repository dropdown — switch it to esphome/esphome-devices and make sure the base branch is main before clicking Create pull request.

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
---

Field	Description	Allowable Options	Required?
title	Device Title		Yes
date-published	Date Published	Formatting: YYYY-MM-DD HH:MM:SS +/-TTTT (Time and Timezone offset are optional)	Yes
type	Type of Device	dimmer, light, misc, plug, relay, sensor, switch	Yes
standard	Electrical standard country	au, br, eu, global, in, uk, us	Yes
board	Type of board used in product	bk72xx, esp32, esp8266, rp2040, rtl87xx	No (but required to show on Boards page)
project-url	URL for product or GitHub. Points to working Yaml file or page where yaml file is easily accessible		No
made-for-esphome	Has the manufacturer certified the device for ESPHome	True, False	No
difficulty	Difficulty rating	1: Comes with ESPHome, 2: Plug-n-flash, 3: Disassembly required, 4: Soldering required, 5: Chip needs replacement	No

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")