2026.2.0

.devcontainer/devcontainer.json

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

.github/PULL_REQUEST_TEMPLATE.md

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

.github/copilot-instructions.md

@@ -5,55 +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.
+- **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.
+  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:
+
+```markdown
+> [!NOTE]
+> Important information
 
-Avoid the use of flowery language and weasel-words that add no useful content; Keep comments concise and technically
+> [!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".
-
-## Legacy Hugo Shortcodes
-
-The following Hugo shortcodes are legacy and should be replaced when encountered:
-* `{{< docref >}}`: use standard Markdown links instead
-* `{{< img >}}`: use standard Markdown image syntax instead

.github/dependabot.yml

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

.github/workflows/ci.yml

@@ -16,48 +16,35 @@ jobs:
     name: Build
     runs-on: ubuntu-latest
     steps:
-      - name: Install pagefind
-        uses: jaxxstorm/action-install-gh-release@6096f2a2bbfee498ced520b6922ac2c06e990ed2 # v2.1.0
-        with:
-          repo: cloudcannon/pagefind
-
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - name: Set up Hugo
-        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
+      - name: Set up Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
         with:
-          hugo-version: 'latest'
-          extended: true
+          node-version: '20'
+          cache: 'npm'
 
-      - name: Set up Python 3.12
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
-        with:
-          python-version: 3.12
+      - name: Install dependencies
+        run: npm ci
 
-      - name: Install Python dependencies
-        run: pip install -r requirements_test.txt
-
-      - name: Run production build
-        run: make production
+      - name: Build
+        run: npm run build
   lint:
     name: Lint
     runs-on: ubuntu-latest
     steps:
     - name: Checkout
       uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-    - name: Set up Python 3.12
-      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+    - name: Set up Node.js
+      uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
       with:
-        python-version: 3.12
+        node-version: '20'
+        cache: 'npm'
 
     - name: Install dependencies
-      run: pip install -r requirements_test.txt
-
-    - name: Register problem matchers
-      run: |
-        echo "::add-matcher::.github/workflows/matchers/ci-custom.json"
+      run: npm ci
 
     - name: markdownlint-cli
       uses: nosborn/github-action-markdown-cli@508d6cefd8f0cc99eab5d2d4685b1d5f470042c1 # v3.5.0
@@ -66,4 +53,4 @@ jobs:
         files: .
 
     - name: Lint
-      run: python lint.py
+      run: npm run lint