Merge origin/next and resolve conflicts

Author: bdraco

.github/copilot-instructions.md

@@ -0,0 +1,55 @@
+# ESPHome Documentation AI Collaboration Guide
+
+This document provides context for AI models interacting with this project.
+Adhering to these guidelines will promote consistency and content quality.
+
+## Project Overview & Purpose
+
+*   **Primary Goal:** ESPHome is a system to configure microcontrollers (like ESP32, ESP8266, RP2040, and LibreTiny-based chips)
+    using simple yet powerful YAML configuration files. It generates C++ firmware that can be compiled and flashed to
+    these devices, allowing users to control them remotely through home automation systems.
+ 
+    This repo is the source for the primary documentation for users of ESPHome, published on [esphome.io](https://esphome.io).
+*   **Business Domain:** Internet of Things (IoT), Home Automation.
+
+## Core Technologies & Stack
+
+*  **Languages:** HTML, CSS, Markdown, Go templates
+*  **Frameworks & Runtimes:** Hugo and Pagefind
+*  **Key Libraries/Dependencies:**
+    * **Hugo:** For building the static site.
+    * **Pagefind:** For client-side text searching
+
+## Architectural Patterns
+
+See the README.md file.
+
+## Branches
+
+* **Current**
+  The `current` branch represents the published documentation in sync with the latest ESPHome release.
+  PRs may be raised against this where they contain documentation revisions only.
+* **Next**
+  The `next` branch is where changes are made via PR corresponding to new features in the ESPHome code repo
+  (esphome/esphome). When a release is made this branch is merged into current.
+
+## Development & Testing Workflow
+
+See the README.md file
+
+## Contribution Workflow (Pull Request Process)
+1.  **Fork:** Fork the repository.
+1.  **Branch:** Create a new branch in your fork from the appropriate base branch (`current` or `next`.)
+1.  **Make Changes:** Adhere to all coding conventions and patterns.
+1.  **Test:** Use the `make live-html` command to invoke hugo in server mode for instant preview.
+1.  **Commit:** Commit your changes. There is no strict format for commit messages.
+1.  **Pull Request:** Submit a PR against the base branch. The Pull Request title should have a prefix of the component being worked on (e.g., `[display] Add new examples`, `[abc123] Add new component`). Pull requests should always be made with the PULL_REQUEST_TEMPLATE.md template filled out correctly.
+
+## Guidelines for AI generated reviews and PR summaries
+
+Avoid the use of flowery language and weasel-words that add no useful content; Keep comments concise and technically
+accurate - you are not writing a press release.
+For example instead of "Created comprehensive documentation with configuration examples and setup instructions"
+it is sufficient to say "Created documentation with examples and instructions".
+
+

.github/workflows/auto-label-pr.yml

@@ -26,11 +26,11 @@ jobs:
     if: github.event.action != 'labeled' || github.event.sender.type != 'Bot'
     steps:
       - name: Checkout
-        uses: actions/checkout@v4.2.2
+        uses: actions/checkout@v5.0.0
 
       - name: Generate a token
         id: generate-token
-        uses: actions/create-github-app-token@v2.0.6
+        uses: actions/create-github-app-token@v2.1.1
         with:
           app-id: ${{ secrets.ESPHOME_GITHUB_APP_ID }}
           private-key: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}

.github/workflows/docker.yml

@@ -30,7 +30,7 @@ jobs:
           repo: cloudcannon/pagefind
       -
         name: Checkout source code
-        uses: actions/checkout@v4.2.2
+        uses: actions/checkout@v5.0.0
       -
         name: Set up QEMU
         uses: docker/setup-qemu-action@v3

.github/workflows/lint.yml

@@ -23,7 +23,7 @@ jobs:
       uses: jaxxstorm/[email protected]
       with:
           repo: cloudcannon/pagefind
-    - uses: actions/checkout@v4.2.2
+    - uses: actions/checkout@v5.0.0
     - name: Set up Python 3.12
       uses: actions/setup-python@v5
       with:
@@ -33,8 +33,10 @@ jobs:
     - name: Register problem matchers
       run: |
         echo "::add-matcher::.github/workflows/matchers/ci-custom.json"
-
+    - name: markdownlint-cli
+      uses: nosborn/[email protected]
+      with:
+        config_file: ".markdownlintrc"
+        files: .
     - name: Lint
       run: python lint.py
-    - name: html-strict
-      run: make html-strict

.gitignore

@@ -1,6 +1,19 @@
+public/
+esphome-docs
+.hugo_build.lock
+.idea
+/node_modules/
+/pagefind/
+/data/repo.yaml
+/data/anchors.json
+/data/automations
+my-secrets
+resources/_gen
+
 _build
 .DS_Store
 
+.cache/
 .python-version
 __pycache__/
 *.py[cod]

.markdownlintignore

@@ -0,0 +1 @@
+LICENSE.md

.markdownlintrc

@@ -0,0 +1,31 @@
+{
+  "default": true,
+  "MD004": {
+    "Style": "dash"
+  },
+  "MD013": false,
+  "MD024": {
+    "siblings_only": true
+  },
+  "MD029": {
+    "style": "one"
+  },
+  "MD041": {
+    "front_matter_title": "^\\s*(?:(?:title\\s*[:=])|(?:headless:\\s*true))"
+  },
+  "MD046": {
+    "style": "fenced"
+  },
+  "MD033": {
+    "allowed_elements": [
+      "details",
+      "summary",
+      "a",
+      "picture",
+      "source",
+      "img"
+    ]
+  },
+  "MD051": false,
+  "MD052": false
+}

.pre-commit-config.yaml

@@ -23,3 +23,7 @@ repos:
           - --branch=current
           - --branch=next
           - --branch=beta
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.45.0
+    hooks:
+    - id: markdownlint

CODE_OF_CONDUCT.md

@@ -34,7 +34,7 @@ This Code of Conduct applies both within project spaces and in public spaces whe
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at <[email protected]>. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
 

LICENSE.md

@@ -16,7 +16,7 @@ Creative Commons public licenses provide a standard set of terms and conditions
 
 By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.
 
-### Section 1 – Definitions.
+### Section 1 – Definitions
 
 a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.
 
@@ -46,7 +46,7 @@ k. __Sui Generis Database Rights__ means rights other than copyright resulting f
 
 l. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.
 
-### Section 2 – Scope.
+### Section 2 – Scope
 
 a. ___License grant.___
 
@@ -80,7 +80,7 @@ b. ___Other rights.___
 
    3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties, including when the Licensed Material is used other than for NonCommercial purposes.
 
-### Section 3 – License Conditions.
+### Section 3 – License Conditions
 
 Your exercise of the Licensed Rights is expressly made subject to the following conditions.
 
@@ -118,7 +118,7 @@ In addition to the conditions in Section 3(a), if You Share Adapted Material You
 
 3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply.
 
-### Section 4 – Sui Generis Database Rights.
+### Section 4 – Sui Generis Database Rights
 
 Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:
 
@@ -130,15 +130,15 @@ c. You must comply with the conditions in Section 3(a) if You Share all or a sub
 
 For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
 
-### Section 5 – Disclaimer of Warranties and Limitation of Liability.
+### Section 5 – Disclaimer of Warranties and Limitation of Liability
 
 a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__
 
 b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__
 
 c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
 
-### Section 6 – Term and Termination.
+### Section 6 – Term and Termination
 
 a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.
 
@@ -154,13 +154,13 @@ c. For the avoidance of doubt, the Licensor may also offer the Licensed Material
 
 d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
 
-### Section 7 – Other Terms and Conditions.
+### Section 7 – Other Terms and Conditions
 
 a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.
 
 b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.
 
-### Section 8 – Interpretation.
+### Section 8 – Interpretation
 
 a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.