Merge remote-tracking branch 'upstream/next' into feature/lvgl-groups

Author: Manoel Amaro

.claude/instructions.md

@@ -0,0 +1,68 @@
+---
+name: pr-workflow
+description: Create pull requests for esphome-docs. Use when creating PRs, submitting changes, or preparing contributions.
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+# ESPHome Docs PR Workflow
+
+When creating a pull request for esphome-docs, follow these steps:
+
+## 1. Create Branch from Upstream
+
+Always base your branch on **upstream** (not origin/fork) to ensure you have the latest code:
+
+```bash
+git fetch upstream
+git checkout -b <branch-name> upstream/current
+```
+
+Use `upstream/current` for documentation fixes, or `upstream/next` for new component docs.
+
+## 2. Read the PR Template
+
+Before creating a PR, read `.github/PULL_REQUEST_TEMPLATE.md` to understand required fields.
+
+## 3. Create the PR
+
+Use `gh pr create` with the **full template** filled in. Never skip or abbreviate sections.
+
+Required fields:
+- **Description**: What changes are being made
+- **Related issue**: Use `fixes <link>` syntax if applicable
+- **Pull request in esphome**: Link if this documents a new feature
+- **Checklist**: Check the appropriate boxes:
+  - `next` branch: New docs with matching esphome PR
+  - `current` branch: Fixes/adjustments to existing docs
+  - Component index: Check if link added to `/components/_index.md`
+
+## 4. Example PR Body
+
+```markdown
+## Description:
+
+<describe your changes here>
+
+**Related issue (if applicable):** fixes https://github.com/esphome/esphome-docs/issues/XXX
+
+**Pull request in [esphome](https://github.com/esphome/esphome) with YAML changes (if applicable):**
+
+- N/A (or esphome/esphome#XXX)
+
+## Checklist:
+
+  - [ ] I am merging into `next` because this is new documentation that has a matching pull-request in [esphome](https://github.com/esphome/esphome) as linked above.
+    or
+  - [x] I am merging into `current` because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.
+
+  - [ ] Link added in `/components/_index.md` when creating new documents for new components or cookbook.
+```
+
+## 5. Push and Create PR
+
+```bash
+git push -u origin <branch-name>
+gh pr create --repo esphome/esphome-docs --base current --title "[component] Brief description"
+```
+
+Use `--base next` if documenting a new feature with a matching esphome PR.

.claude/skills/pr-workflow/SKILL.md

@@ -1,19 +1,45 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.177.0/containers/typescript-node
 {
-  "name": "ESPHome - docs",
-  "image": "mcr.microsoft.com/devcontainers/python:3.13",
-  "postCreateCommand": ".devcontainer/postCreate.sh",
-  "postAttachCommand": "make live-html",
+  "name": "ESPHome Astro Dev Container",
+  "image": "mcr.microsoft.com/devcontainers/typescript-node:22-bookworm",
   "forwardPorts": [
-    8000
+    4321
   ],
-  "features": {
-    "ghcr.io/devcontainers/features/github-cli:1": {}
+  "portsAttributes": {
+    "4321": {
+      "label": "Preview"
+    }
   },
+  // Add the IDs of extensions you want installed when the container is created.
   "customizations": {
     "vscode": {
       "extensions": [
-        "ms-python.python"
-      ]
+        "astro-build.astro-vscode",
+        "vunguyentuan.vscode-css-variables",
+        "esbenp.prettier-vscode",
+        "yzhang.markdown-all-in-one",
+        "davidanson.vscode-markdownlint",
+        "jock.svg"
+      ],
+      "settings": {
+        "files.eol": "\n",
+        "editor.tabSize": 2,
+        "editor.formatOnPaste": false,
+        "editor.formatOnSave": true,
+        "editor.formatOnType": true,
+        "[typescript]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode"
+        },
+        "[javascript]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode"
+        },
+        "files.trimTrailingWhitespace": true
+      }
     }
-  }
+  },
+  "postCreateCommand": "npm install",
+  // Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+  "remoteUser": "node"
+  // moved settings under customizations.vscode.settings
 }

.devcontainer/devcontainer.json

@@ -7,3 +7,4 @@
 *.mp3 binary
 *.gif binary
 *.avif binary
+*.webp binary

.devcontainer/postCreate.sh

@@ -1,19 +1,20 @@
-## Description:
+<!-- markdownlint-disable -->
 
+## Description
 
 **Related issue (if applicable):** fixes <link to issue>
 
-**Pull request in [esphome](https://github.com/esphome/esphome) with YAML changes (if applicable):** 
+**Pull request in [esphome](https://github.com/esphome/esphome) with YAML changes (if applicable):**
 
 - esphome/esphome#<esphome PR number goes here>
 
-## Checklist:
+## Checklist
 
-  - [ ] I am merging into `next` because this is new documentation that has a matching pull-request in [esphome](https://github.com/esphome/esphome) as linked above.  
-    or
-  - [ ] I am merging into `current` because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.
+- [ ] I am merging into `next` because this is new documentation that has a matching pull-request in [esphome](https://github.com/esphome/esphome) as linked above.
+  or
+- [ ] I am merging into `current` because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.
 
-  - [ ] Link added in `/components/_index.md` when creating new documents for new components or cookbook.
+- [ ] Link added in `/src/content/docs/components/index.mdx` when creating new documents for new components or cookbook.
 
 <details>
 <summary><strong>New Component Images</strong></summary>
@@ -30,13 +31,16 @@ If you are adding a new component to ESPHome, you can automatically generate a s
 
 2. The ESPHome bot will respond with a downloadable ZIP file containing the SVG image.
 
-3. Extract the SVG file and place it in the `/static/images/` folder of this repository.
+3. Extract the SVG file and place it in the `/public/images/` folder of this repository.
 
-4. Use the image in your component's index table entry in `/components/_index.md`.
+4. Use the image in your component's index table entry in `/src/content/docs/components/index.mdx`.
 
 **Example:** For a component called "DHT22 Temperature Sensor", use:
+
 ```
 @esphomebot generate image dht22
 ```
 
+**Note:** All images used in ImgTable components must be placed in `/public/images/` as the component resolves them to absolute paths.
+
 </details>

.gitattributes

@@ -5,51 +5,138 @@ 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.
+- **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
+- **Languages:** TypeScript, MDX (Markdown with JSX), CSS, JavaScript
+- **Frameworks & Runtimes:** Astro, Starlight, Node.js
+- **Key Libraries/Dependencies:**
+  - **Astro:** Static site generator with component-based architecture
+  - **Starlight:** Documentation framework built on Astro
+  - **Pagefind:** Client-side text searching
+  - **KaTeX:** Mathematical equation rendering
+  - **remark-github-blockquote-alert:** GitHub-flavored alert boxes
 
 ## Architectural Patterns
 
-See the README.md file.
+See the README.md file for detailed information about:
+
+- Project structure (Astro/Starlight conventions)
+- Image handling (local imports vs. absolute paths)
+- MDX format and component usage
+- Custom Astro components
+
+## Content Format
+
+- **File Format:** MDX (`.mdx` files in `src/content/docs/`)
+- **Frontmatter:** Required YAML frontmatter with `title` and `description`
+- **Images:**
+  - Single-use images: Import locally from `./images/` directory
+  - Multi-use images: Use absolute paths from `/public/images/`
+  - ImgTable images: Must be in `/public/images/`
+- **Components:** Import Astro components using `@components/` alias
 
 ## Branches
 
-* **Current**
+- **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**
+- **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
 
+Quick start:
+
+1. Install dependencies: `npm install`
+1. Run dev server: `npm run dev`
+1. View at: `http://localhost:4321/`
+
 ## 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
+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 `npm run dev` to run the development server 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.
+
+## MDX Writing Guidelines
+
+### Images
+
+**Single-use images (used in one file only):**
+
+```mdx
+import { Image } from 'astro:assets';
+import myImageImg from './images/my-image.jpg';
+
+<Image src={myImageImg} alt="Description" layout="constrained" />
+```
+
+**Multi-use images (used in multiple files):**
+
+```mdx
+<Image src="/images/shared-image.jpg" alt="Description" layout="constrained" />
+```
+
+**Important:** All images used in ImgTable components MUST be in `/public/images/` with absolute paths.
+
+### Alert Boxes
+
+Use GitHub-flavored alert syntax:
 
-Avoid the use of flowery language and weasel-words that add no useful content; Keep comments concise and technically
+```markdown
+> [!NOTE]
+> Important information
+
+> [!WARNING]
+> Warning message
+
+> [!TIP]
+> Helpful tip
+```
+
+### Components
+
+Import custom components:
+
+```mdx
+import APIRef from '@components/APIRef.astro';
+import Figure from '@components/Figure.astro';
+import myImageImg from './images/my-image.jpg';
+
+<APIRef text="component.h" path="component/component.h" />
+
+<Figure src={myImageImg} alt="Description" caption="Optional caption" />
+```
+
+### Mathematical Expressions
+
+Use LaTeX syntax with KaTeX:
+
+```markdown
+Inline: $E = mc^2$
+
+Block:
+$$
+\text{formula} = \frac{a}{b}
+$$
+```
+
+## 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/PULL_REQUEST_TEMPLATE.md

@@ -5,7 +5,7 @@ updates:
     schedule:
       interval: daily
     open-pull-requests-limit: 10
-  - package-ecosystem: pip
+  - package-ecosystem: npm
     directory: "/"
     schedule:
       interval: daily

.github/copilot-instructions.md

@@ -26,7 +26,7 @@ jobs:
     if: github.event.action != 'labeled' || github.event.sender.type != 'Bot'
     steps:
       - name: Checkout
-        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Generate a token
         id: generate-token