Merge branch 'next'

Author: CzBiX

.devcontainer/devcontainer.json

@@ -1,15 +1,19 @@
 {
   "name": "ESPHome - docs",
-  "image": "mcr.microsoft.com/devcontainers/python:3.12",
+  "image": "mcr.microsoft.com/devcontainers/python:3.13",
   "postCreateCommand": ".devcontainer/postCreate.sh",
   "postAttachCommand": "make live-html",
-  "forwardPorts": [8000],
+  "forwardPorts": [
+    8000
+  ],
   "features": {
     "ghcr.io/devcontainers/features/github-cli:1": {}
   },
   "customizations": {
     "vscode": {
-      "extensions": ["ms-python.python"]
+      "extensions": [
+        "ms-python.python"
+      ]
     }
   }
 }

.devcontainer/postCreate.sh

@@ -1,5 +1,21 @@
 #!/bin/bash
+set -euo pipefail
 
+sudo apt update && sudo apt install -y hugo
 
-pip3 install -r requirements.txt -r requirements_test.txt
-curl -L https://github.com/CloudCannon/pagefind/releases/download/v1.1.0/pagefind-v1.1.0-x86_64-unknown-linux-musl.tar.gz | tar -xz -C ~/.local/bin
+pip3 install -r requirements_test.txt
+pre-commit install
+
+mkdir -p ~/.local/bin
+
+ARCH="$(uname -m)"
+case "$ARCH" in
+  x86_64) PAGEFIND_ARCH="x86_64" ;;
+  arm64|aarch64) PAGEFIND_ARCH="aarch64" ;;
+  *)
+    echo "Unsupported architecture: $ARCH" >&2
+    exit 1
+    ;;
+esac
+curl -L "https://github.com/CloudCannon/pagefind/releases/download/v1.3.0/pagefind-v1.3.0-${PAGEFIND_ARCH}-unknown-linux-musl.tar.gz" \
+  | tar -xz -C ~/.local/bin

.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,17 +26,17 @@ jobs:
     if: github.event.action != 'labeled' || github.event.sender.type != 'Bot'
     steps:
       - name: Checkout
-        uses: actions/checkout@v4.2.2
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # 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@a8d616148505b5069dccd32f177bb87d7f39123b # v2.1.1
         with:
           app-id: ${{ secrets.ESPHOME_GITHUB_APP_ID }}
           private-key: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}
 
       - name: Auto Label PR
-        uses: actions/github-script@v7.0.1
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
         env:
           PR_NUMBER: ${{ github.event.inputs.pr_number || github.event.number }}
         with:

.github/workflows/component-image.yml

@@ -19,7 +19,7 @@ jobs:
     steps:
       - name: Comment
         id: create-comment
-        uses: actions/github-script@v7.0.1
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
         with:
           script: |
             const result = await github.rest.issues.createComment({
@@ -45,19 +45,19 @@ jobs:
     needs: prepare
     steps:
       - name: Generate
-        uses: esphome/component-image-generator@v1.0.0
+        uses: esphome/component-image-generator@d0d2a195b500e8c37c17f299ff6b90933f2197cf # v1.0.0
         with:
           component: ${{ needs.prepare.outputs.name }}
 
       - name: Upload
-        uses: actions/upload-artifact@v4.6.2
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         id: upload-artifact
         with:
           name: ${{ needs.prepare.outputs.name }}
           path: ${{ needs.prepare.outputs.name_lower }}.svg
 
       - name: Update Comment
-        uses: actions/github-script@v7.0.1
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
         with:
           script: |
             await github.rest.issues.updateComment({

.github/workflows/docker.yml

@@ -6,12 +6,10 @@ on:
     branches:
       - current
     paths:
-      - requirements.txt
       - Dockerfile
       - .github/workflows/docker.yml
   pull_request:
     paths:
-      - requirements.txt
       - Dockerfile
       - .github/workflows/docker.yml
 
@@ -25,36 +23,36 @@ jobs:
     steps:
       -
         name: Install pagefind
-        uses: jaxxstorm/action-install-gh-release@v2.1.0
+        uses: jaxxstorm/action-install-gh-release@6096f2a2bbfee498ced520b6922ac2c06e990ed2 # v2.1.0
         with:
           repo: cloudcannon/pagefind
       -
         name: Checkout source code
-        uses: actions/checkout@v4.2.2
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       -
         name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@29109295f81e9208d7d86ff1c6c12d2833863392 # v3
       -
         name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3
       -
         name: Login to DockerHub
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@v3
+        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3
         with:
           username: ${{ secrets.DOCKER_USER }}
           password: ${{ secrets.DOCKER_PASSWORD }}
       - name: Login to GitHub Container Registry
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@v3
+        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
       -
         name: Build and push
         id: docker_build
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6
         with:
           context: .
           push: ${{ github.event_name != 'pull_request' }}

.github/workflows/labeller-recheck.yml

@@ -15,7 +15,7 @@ jobs:
     if: github.event.label.name == 'labeller-recheck'
     steps:
       - name: Call Auto Label workflow
-        uses: actions/github-script@v7.0.1
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |

.github/workflows/lint.yml

@@ -20,21 +20,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Install pagefind
-      uses: jaxxstorm/action-install-gh-release@v2.1.0
+      uses: jaxxstorm/action-install-gh-release@6096f2a2bbfee498ced520b6922ac2c06e990ed2 # v2.1.0
       with:
           repo: cloudcannon/pagefind
-    - uses: actions/checkout@v4.2.2
+    - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
     - name: Set up Python 3.12
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6
       with:
         python-version: 3.12
     - name: Install dependencies
-      run: pip install -r requirements.txt -r requirements_test.txt
+      run: pip install -r requirements_test.txt
     - name: Register problem matchers
       run: |
         echo "::add-matcher::.github/workflows/matchers/ci-custom.json"
-
+    - name: markdownlint-cli
+      uses: nosborn/github-action-markdown-cli@508d6cefd8f0cc99eab5d2d4685b1d5f470042c1 # v3.5.0
+      with:
+        config_file: ".markdownlintrc"
+        files: .
     - name: Lint
       run: python lint.py
-    - name: html-strict
-      run: make html-strict

.github/workflows/lock.yml

@@ -16,7 +16,7 @@ jobs:
   lock:
     runs-on: ubuntu-latest
     steps:
-      - uses: dessant/lock-threads@v4
+      - uses: dessant/lock-threads@be8aa5be94131386884a6da4189effda9b14aa21 # v4
         with:
           pr-inactive-days: "1"
           pr-lock-reason: ""

.github/workflows/stale.yml

@@ -16,7 +16,7 @@ jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v8
+      - uses: actions/stale@3a9db7e6a41a89f618792c92c0e97cc736e1b13f # v10
         with:
           days-before-pr-stale: 60
           days-before-pr-close: 7
@@ -30,19 +30,3 @@ jobs:
             pull request has been automatically marked as stale because of that
             and will be closed if no further activity occurs within 7 days.
             Thank you for your contributions.
-
-  # Use stale to automatically close issues with a reference to the issue tracker
-  close-issues:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/stale@v8
-        with:
-          days-before-pr-stale: -1
-          days-before-pr-close: -1
-          days-before-issue-stale: 1
-          days-before-issue-close: 1
-          remove-stale-when-updated: true
-          stale-issue-label: "stale"
-          exempt-issue-labels: "not-stale"
-          stale-issue-message: >
-            https://github.com/esphome/esphome-docs/issues/162