Merge branch 'master' into vitepress

Author: veeck

.github/workflows/pr-check.yml

@@ -0,0 +1,32 @@
+name: Check Pull Request
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+    branches:
+      - master
+
+concurrency:
+  group: pr-check-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v5
+
+      - name: Install Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: current
+
+      - name: Install Dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Run Tests
+        run: npm run test

.vuepress/config.js

@@ -70,6 +70,7 @@ export default {
           "/module-development/introduction.md",
           "/module-development/core-module-file.md",
           "/module-development/node-helper.md",
+          "/module-development/rendering.md",
           "/module-development/helper-methods.md",
           "/module-development/logger.md",
           "/module-development/notifications.md",
@@ -118,4 +119,3 @@ export default {
     }),
   ],
 };
-

configuration/introduction.md

@@ -59,6 +59,7 @@ The following properties can be configured, place them above the modules item:
 | `electronOptions`  | An optional array of Electron (browser) options. This allows configuration of e.g. the browser screen size and position (example: `electronOptions: { fullscreen: false, width: 800, height: 600 }`). Kiosk mode can be enabled by setting `kiosk: true`, `autoHideMenuBar: false` and `fullscreen: false`. More options can be found [here](https://github.com/electron/electron/blob/master/docs/api/browser-window.md). This will most likely be used in advanced installations, below.                                                                | []                                         |
 | `electronSwitches` | An optional array of Electron switches. This allows configuration of electron app itself. <br> This properties will not affect the `serveronly` mode. Usually normal `MM` users don't need this property, but if you are a hard-core hacker, you might need this to handle Electron itself over `MagicMirror` provides. More options can be found [here](https://www.electronjs.org/docs/latest/api/command-line-switches) (Not all available switches are described there.)<br>example:`electronSwitches:["enable-transparent-visuals", "disable-gpu"];` | []                                         |
 | `customCss`        | The path of the `custom.css` stylesheet. The default is `css/custom.css`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `css/custom.css`                           |
+| `watchTargets`     | An optional array of file paths to monitor when using `node --run server:watch`. When any of these files change, the server automatically restarts and connected browsers reload. Particularly useful when frequently modifying `config.js`, `custom.css`, or module files during development or setup. Example: `watchTargets: ["config/config.js", "css/custom.css", "modules/MMM-MyModule/MMM-MyModule.js"]`. See [Development Mode](/core-development/debugging.html#development-mode-with-auto-reload) for more details.                             | `undefined`                                |
 
 After the above options, you will then add modules. See
 [module configuration](/modules/configuration.md) for more information.
@@ -74,7 +75,7 @@ are:
 | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | MM_CONFIG_FILE            | This specifies an alternate configuration file for the system. This is useful when running multiple mirrors on the same device. This does not work with the template option below. NOTE: this file **_MUST_** be located in a directory within the MagicMirror directory. Ideally, place any config file in the config subdirectory. |
 | MM_PORT                   | This specifies an alternate TCP/IP port, overriding "port" item within the config file. This is useful for testing to see if the product will run using another port.                                                                                                                                                                |
-| mmFetchTimeout            | time in milliseconds for fetch timeout. default (30000) <br><br>this value can be used to adjust the nodejs fetch function timeout value (default 10 seconds) for all node_helper modules that use fetch()                                                                                                                           |
+| mmFetchTimeout            | time in milliseconds for fetch timeout. default (30000) <br><br>this value can be used to adjust the nodejs fetch function timeout value for all node_helper modules that use fetch()                                                                                                                                                |
 
 #### Examples of use
 

configuration/raspberry.md

@@ -1,20 +1,24 @@
 # Raspberry Specific
 
-This information here is based on the latest release of 
-[Raspberry Pi OS](https://www.raspberrypi.com/software/operating-systems/) ("Trixie") from October 1st 2025.
+This information here is based on the latest release of
+[Raspberry Pi OS](https://www.raspberrypi.com/software/operating-systems/)
+("Trixie") from October 1st 2025.
 
 ## Adding colored icons
 
-Raspberry Pi OS does not come with colored emoji icons by default. To add them, install the following package:
+Raspberry Pi OS does not come with colored emoji icons by default. To add them,
+install the following package:
 
 ```shell
 sudo apt install fonts-noto-color-emoji
 ```
 
 ## Rotating the screen
 
-See the [official documentation](https://www.raspberrypi.com/documentation/computers/configuration.html#set-resolution-and-rotation)
+See the
+[official documentation](https://www.raspberrypi.com/documentation/computers/configuration.html#set-resolution-and-rotation)
 
-In case you still run an older version of the Raspberry Pi OS, you can follow these instructions:
+In case you still run an older version of the Raspberry Pi OS, you can follow
+these instructions:
 
 https://pimylifeup.com/raspberry-pi-rotate-screen/

core-development/debugging.md

@@ -30,18 +30,57 @@ Developer consoles in browsers and the Electron app (typically CTRL+SHIFT+I to
 toggle open/close) can be used to set client-side breakpoints, step through
 scripts and inspect variables.
 
+## Watch Mode with Auto-Reload
+
+For active development, MagicMirror² provides a `server:watch` script that
+automatically restarts the server and reloads connected browsers when files
+change:
+
+```sh
+node --run server:watch
+```
+
+This mode monitors files specified in your `config.js` under the `watchTargets`
+property:
+
+```js
+let config = {
+  watchTargets: [
+    "config/config.js",
+    "css/custom.css",
+    "modules/MMM-MyModule/MMM-MyModule.js",
+    "modules/MMM-MyModule/node_helper.js",
+  ],
+  // ... rest of config
+};
+```
+
+When any monitored file changes:
+
+1. The server automatically restarts
+2. Waits for the port to become available
+3. Sends a reload notification to all connected browsers via Socket.io
+4. Browsers automatically refresh to show the changes
+
+This creates a seamless development experience where you can edit code, save,
+and see the results within seconds without manual restarts.
+
+**Note:** If `watchTargets` is empty or undefined, the watcher starts but
+monitors nothing.
+
 ## Logging
 
 While there are no log files produced by the server, info is reported in two
 different places:
 
-- The console when running from `npm run start` or `npm run server`.
+- The console when running from `node --run start`, `node --run server`, or
+  `node --run server:watch`.
   - This is separated into two streams, `console.log()` is output as the
     `stdout` stream, and
   - `console.error()` is output as the `stderr` stream.
   - These can be redirected to files when starting the server. `>` will redirect
     `stdout`, and `2>` will redirect `stderr`. `2>&1` will combine both streams:
-    `npm run start > out.log 2>&1`
+    `node --run start > out.log 2>&1`
 - The browser's developer console (typically CTRL+SHIFT+I to toggle open/close)
   will have output from scripts that run on the browser.
 
@@ -113,5 +152,5 @@ script, such as `start:dev`:
 Or when running from the command line (Linux example):
 
 ```sh
-TZ=Europe/Madrid npm run start:dev
+TZ=Europe/Madrid node --run start:dev
 ```

cspell.config.json

@@ -2,7 +2,6 @@
   "version": "0.2",
   "language": "en",
   "words": [
-    "Deepwiki",
     "anyfileorfolder",
     "apikey",
     "Autorestart",
@@ -12,6 +11,8 @@
     "custommodules",
     "dateheaders",
     "datetype",
+    "Deepwiki",
+    "endfor",
     "envcanada",
     "exploader",
     "feelslike",
@@ -34,6 +35,7 @@
     "newpos",
     "newsfeed",
     "nohup",
+    "noto",
     "oenstrom",
     "onecall",
     "openmeteo",
@@ -59,9 +61,9 @@
     "Teeuw",
     "Termine",
     "timeformat",
+    "Trixie",
     "trunc",
     "tympanus",
-    "ukmetoffice",
     "ukmetofficedatahub",
     "UKMO",
     "updatenotification",

getting-started/installation.md

@@ -27,24 +27,33 @@ the install specific instructions below
 2. Check if `git` is installed on your machine by executing `git` (should show
    usage), otherwise install it
 3. Clone the repository:
+
 ```shell
-   git clone https://github.com/MagicMirrorOrg/MagicMirror
+git clone https://github.com/MagicMirrorOrg/MagicMirror.git
 ```
-4. Enter the repository: 
+
+4. Enter the repository:
+
 ```shell
-  cd MagicMirror
+cd MagicMirror
 ```
+
 5. Install the application: ``
+
 ```shell
-  node --run install-mm
+node --run install-mm
 ```
+
 6. Make a copy of the config sample file:
+
 ```shell
-   cp config/config.js.sample config/config.js
+cp config/config.js.sample config/config.js
 ```
+
 7. Start the application:
+
 ```shell
-  node --run start
+node --run start
 ```
 
 ::: warning NOTE

module-development/core-module-file.md

@@ -205,6 +205,9 @@ starts, or because your module asked a refresh using `this.updateDom()`), the
 system calls the getDom method. This method should therefore return a dom
 object.
 
+Read more about Rendering Components
+[in the Rendering Component documentation](./rendering.md).
+
 **Example:**
 
 ```js
@@ -228,6 +231,9 @@ data to the template with `getTemplateData`.
 An example of a default module that uses this method is
 [newsfeed](https://github.com/MagicMirrorOrg/MagicMirror/blob/master/modules/default/newsfeed/newsfeed.js).
 
+Read more about Rendering Components
+[in the Rendering Component documentation](./rendering.md).
+
 **Example:**
 
 ```js

module-development/rendering.md

@@ -0,0 +1,107 @@
+# Rendering Component
+
+There are two main approaches to rendering your component. Procedurally
+generating a Dom object with `getDom`, or using the built in Nunjucks templating
+engine.
+
+With both approaches, rendering is first triggered when the module is first
+loaded. When your module's data changes, you can call
+[`this.updateDom()`](/module-development/core-module-file.md#thisupdatedomsspeed)
+to trigger a re-render.
+
+## Using `getDom`
+
+The `getDom` method is called by MagicMirror whenever it needs to update
+information on the screen. This method should return an HTML
+[Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) which
+contains all the information you would like to display.
+
+**Example:**
+
+```js
+getDom: function() {
+	const wrapper = document.createElement("div");
+	wrapper.innerHTML = 'Hello world!';
+	return wrapper;
+}
+```
+
+## Using Nunjucks Templates
+
+If `getDom` is not overridden, MagicMirror will try and render a
+[Nunjucks](https://mozilla.github.io/nunjucks/) template from `getTemplate`.
+
+Nunjucks is a templating language for JavaScript. You can read more about the
+syntax in the
+[Nunjucks Documentation](https://mozilla.github.io/nunjucks/templating.html).
+
+### Templates and Data
+
+Templates are rendered by calling `getTemplate` to get the path to the template
+and `getTemplateData` to get the data used in the template.
+
+**Example:**
+
+`MMM-MyModule.js`
+
+```js
+getTemplate: function() {
+  return "MMM-MyModule.njk";
+},
+
+getTemplateData: function() {
+  return {
+    list: ["item 1", "item 2", "item 3"],
+  };
+}
+```
+
+`MMM-MyModule.njk`
+
+```nunjucks
+<ul>
+  {% for item in list %}
+  <li>{{ item }}</li>
+  {% endfor %}
+</ul>
+```
+
+Rendered HTML:
+
+```html
+<ul>
+  <li>item 1</li>
+  <li>item 2</li>
+  <li>item 3</li>
+</ul>
+```
+
+### Filters
+
+[Nunjucks Filters](https://mozilla.github.io/nunjucks/templating.html#filters)
+are functions added to Nunjucks that can be applied to variables passed to the
+template.
+
+#### `translate` filter
+
+MagicMirror provides a `translate` filter which can be used to access the same
+functionality available in the
+[`this.translate` module instance method](/module-development/core-module-file.md#thistranslateidentifier).
+
+```nunjucks
+{{ "INFO" | translate }}
+```
+
+#### Adding filters
+
+You can add your own filters by accessing the Nunjucks environment via
+`this.nunjucksEnvironment()`
+
+```js
+this.nunjucksEnvironment().addFilter("space", function (str) {
+  return str.split("").join(" ");
+});
+```
+
+For filter examples see the
+[`weather` module](https://github.com/MagicMirrorOrg/MagicMirror/blob/master/modules/default/weather/weather.js#L221).

modules/compliments.md

@@ -34,7 +34,7 @@ The following properties can be configured:
 | `fadeSpeed`                 | Speed of the update animation. (Milliseconds) <br><br> **Possible values:**`0` - `5000` <br> **Default value:** `4000` (4 seconds)                                                                                                                                                                                                                                                                                                                               |
 | `compliments`               | The list of compliments. <br><br> **Possible values:** An object with four arrays: `morning`, `afternoon`, `evening` and `anytime`. See _compliment configuration_ below. <br> **Default value:** See _compliment configuration_ below.                                                                                                                                                                                                                          |
 | `remoteFile`                | External file from which to load the compliments <br><br> **Possible values:** Path or URL (starting with `http://` or `https://`) to a JSON file containing compliments, configured as per the value of the _compliments configuration_ (see below). An json object {} with at least one of the arrays: `morning`, `afternoon`, `evening`, `anytime`, `datetype` and/or `crontype`. - `compliments.json` <br> **Default value:** `null` (Do not load from file) |
-| `remoteFileRefreshInterval` | How often to reload the remote file, if remoteFile is specified. in ms <br> **Default value:** 0 <br> **Minimum value:** 15 minutes (15\*60\*60\*1000)                                                                                                                                                                                                                                                                                                           |
+| `remoteFileRefreshInterval` | How often to reload the remote file, if remoteFile is specified. in ms <br> **Default value:** 0 <br> **Minimum value:** 15 minutes (15\*60\*1000)                                                                                                                                                                                                                                                                                                               |
 | `classes`                   | Override the CSS classes of the div showing the compliments <br><br> **Default value:** `thin xlarge bright`                                                                                                                                                                                                                                                                                                                                                     |
 | `morningStartTime`          | Time in hours (in 24 format), after which the mode of "morning" will begin <br> **Possible values:** `0` - `24` <br><br> **Default value:** `3`                                                                                                                                                                                                                                                                                                                  |
 | `morningEndTime`            | Time in hours (in 24 format), after which the mode of "morning" will end <br> **Possible values:** `0` - `24` <br><br> **Default value:** `12`                                                                                                                                                                                                                                                                                                                   |