Enhance documentation with Windows line endings guidance and add references to DocTest validation plugin examples across multiple files

Author: mstrhakr

docs/advanced/debugging-techniques.md

@@ -173,6 +173,33 @@ bash -n /path/to/script.sh
 
 ## Common Issues
 
+### Windows Line Endings (CRLF vs LF)
+
+{: .warning }
+> Scripts developed on Windows will have CRLF line endings (`\r\n`) which cause "bad interpreter" errors on Unraid's Linux system.
+
+**Symptom:**
+```
+bash: /usr/local/emhttp/plugins/myplugin/event/started: /bin/bash^M: bad interpreter: No such file or directory
+```
+
+**Fix during build:**
+```bash
+# Convert all scripts to Unix line endings
+find build/ -type f \( -name "*.sh" -o -name "*.page" \) -exec sed -i 's/\r$//' {} \;
+find build/usr/local/emhttp/plugins/myplugin/event -type f -exec sed -i 's/\r$//' {} \;
+```
+
+**Fix on server:**
+```bash
+cd /usr/local/emhttp/plugins/myplugin/event
+sed -i 's/\r$//' *
+chmod 755 *
+```
+
+{: .note }
+> See the [validation plugin build script](https://github.com/mstrhakr/unraid-plugin-docs/blob/main/validation/plugin/build.sh) for a working example that handles line ending conversion automatically.
+
 ### Permission Problems
 
 ```bash

docs/build-and-packaging.md

@@ -59,6 +59,9 @@ myplugin-1.0.0.txz
 
 ### Creating the TXZ Package
 
+{: .note }
+> See the [DocTest validation plugin build script](https://github.com/mstrhakr/unraid-plugin-docs/blob/main/validation/plugin/build.sh) for a complete working example.
+
 ```bash
 #!/bin/bash
 # pkg_build.sh - Build a Slackware package
@@ -75,17 +78,26 @@ mkdir -p "$BUILD_DIR"
 # Copy source files preserving structure
 cp -R "$SOURCE_DIR"/* "$BUILD_DIR/"
 
+# CRITICAL: Convert Windows line endings to Unix (CRLF → LF)
+# Without this, scripts will fail with "bad interpreter" errors
+find "$BUILD_DIR" -type f \( -name "*.sh" -o -name "*.page" -o -name "*.cfg" \) -exec sed -i 's/\r$//' {} \;
+find "$BUILD_DIR" -path "*/event/*" -type f -exec sed -i 's/\r$//' {} \;
+
 # Set correct permissions
 find "$BUILD_DIR" -type d -exec chmod 755 {} \;
 find "$BUILD_DIR" -type f -exec chmod 644 {} \;
 find "$BUILD_DIR" -name "*.sh" -exec chmod 755 {} \;
+find "$BUILD_DIR" -path "*/event/*" -type f -exec chmod 755 {} \;
 find "$BUILD_DIR/etc/rc.d" -type f -exec chmod 755 {} \;
 
 # Create the package
 cd "$BUILD_DIR"
 makepkg -l y -c n "../${PLUGIN_NAME}-${VERSION}.txz"
 ```
 
+{: .warning }
+> **Windows developers**: Always convert line endings before packaging! Scripts with CRLF line endings will fail with `/bin/bash^M: bad interpreter`. See [Debugging Techniques](advanced/debugging-techniques.md#windows-line-endings-crlf-vs-lf) for more details.
+
 > **Note**: If `makepkg` isn't available (you're building on a non-Slackware system), you can use tar directly:
 > ```bash
 > tar -cJf "../${PLUGIN_NAME}-${VERSION}.txz" .

docs/events.md

@@ -96,6 +96,9 @@ flowchart LR
 
 ## Creating Event Handlers
 
+{: .note }
+> See the [DocTest validation plugin event handlers](https://github.com/mstrhakr/unraid-plugin-docs/blob/main/validation/plugin/source/emhttp/event/) for working examples of all 16 documented events.
+
 ### Directory Structure
 
 ```

docs/getting-started.md

@@ -292,6 +292,29 @@ Refresh the browser to see changes. Remember to copy changes back to your source
 - Check package URL is accessible
 - Look at install output for errors
 
+### "Bad Interpreter" Error
+
+If you see errors like `/bin/bash^M: bad interpreter`, your files have Windows line endings (CRLF). Fix with:
+
+```bash
+# Convert all scripts to Unix line endings
+find . -type f \( -name "*.sh" -o -name "*.page" \) -exec sed -i 's/\r$//' {} \;
+```
+
+{: .warning }
+> **Windows developers**: Always convert line endings before packaging! Add line ending conversion to your build script. See [Debugging Techniques](advanced/debugging-techniques.md#windows-line-endings-crlf-vs-lf) for details.
+
+### Form Layout Issues
+
+If form fields are misaligned, check that you're using the Dynamix markdown syntax with `: ` (colon-space at line start):
+
+```markdown
+_(Label)_:
+: <input type="text" name="field">
+```
+
+**Not** raw `<dl><dt><dd>` HTML inside `markdown="1"` forms. See [Page Files Troubleshooting](page-files.md#content-shifted-or-layout-issues) for details.
+
 ## Next Steps
 
 Now that you have a working plugin:

docs/introduction.md

@@ -154,6 +154,21 @@ This documentation will guide you through:
 4. **[Packaging](packaging.md)** - Building distribution packages
 5. **[Best Practices](best-practices.md)** - Tips from experienced developers
 
+## Working Example: DocTest Validation Plugin
+
+This repository includes a complete, working validation plugin that demonstrates all documented features. You can:
+
+- **[View the source code](https://github.com/mstrhakr/unraid-plugin-docs/tree/main/validation/plugin)** - See how a real plugin is structured
+- **[Install it on your server](https://github.com/mstrhakr/unraid-plugin-docs/blob/main/validation/README.md)** - Test documented features live
+- **[Check validation results](https://github.com/mstrhakr/unraid-plugin-docs/blob/main/validation/results/)** - See what we've verified against Unraid
+
+The DocTest plugin validates:
+- All 16 documented event handlers
+- `parse_plugin_cfg()` and `mk_option()` functions
+- `$var` array properties
+- Page file rendering and form handling
+- Notification system integration
+
 ## Next Steps
 
 Ready to build your first plugin? Continue to [Your First Plugin](getting-started.md) for a hands-on tutorial.

docs/page-files.md

@@ -511,6 +511,7 @@ $containers = $DockerClient->getDockerContainers();
 1. Check Menu attribute matches a valid section
 2. Verify Cond evaluation returns true
 3. Check for PHP syntax errors: `php -l yourfile.page`
+4. Check for Windows line endings (CRLF) - see [Debugging Techniques](advanced/debugging-techniques.md#windows-line-endings-crlf-vs-lf)
 
 ### Form Not Saving
 
@@ -524,6 +525,30 @@ $containers = $DockerClient->getDockerContainers();
 2. Check file paths are correct
 3. Verify files exist in the package
 
+### Content Shifted or Layout Issues
+
+{: .warning }
+> Do not use raw `<dl><dt><dd>` HTML inside `markdown="1"` forms. The Dynamix markdown processor expects the colon syntax.
+
+**Wrong (causes layout shift):**
+```html
+<dl>
+<dt>My Label:</dt>
+<dd><input type="text" name="field"></dd>
+</dl>
+```
+
+**Correct:**
+```markdown
+_(My Label)_:
+: <input type="text" name="field">
+```
+
+The `: ` (colon-space at start of line) creates proper Dynamix field alignment. For read-only display sections outside forms, use standard HTML tables or `<pre>` blocks.
+
+{: .note }
+> See the [DocTest validation plugin](https://github.com/mstrhakr/unraid-plugin-docs/blob/main/validation/plugin/source/emhttp/DocTest.page) for a working example of proper form structure.
+
 ## Next Steps
 
 - Learn about [Page Headers](page-headers.md) for advanced menu options

docs/plg-file.md

@@ -8,6 +8,8 @@ nav_order: 3
 
 {: .note }
 > ✅ **Validated against Unraid 7.2.3** - PLG structure and attributes verified against installed plugins.
+>
+> See the [DocTest validation plugin PLG](https://github.com/mstrhakr/unraid-plugin-docs/blob/main/validation/doctest.plg) for a complete working example.
 
 The `.plg` file is the heart of every Unraid plugin. It's an XML document that tells the plugin system how to install, update, and remove your plugin.
 

docs/reference/php-functions-reference.md

@@ -9,6 +9,8 @@ nav_order: 1
 
 {: .note }
 > ✅ **Validated against Unraid 7.2.3** - Function locations and implementations verified.
+>
+> See the [DocTest validation plugin](https://github.com/mstrhakr/unraid-plugin-docs/blob/main/validation/plugin/source/emhttp/DocTest.page) for a working example that demonstrates `parse_plugin_cfg()`, `mk_option()`, `$var` array access, and more.
 
 {: .warning }
 > This page is a stub. [Help us expand it!](https://github.com/mstrhakr/unraid-plugin-docs/blob/main/CONTRIBUTING.md)

docs/reference/var-array-reference.md

@@ -9,6 +9,8 @@ nav_order: 4
 
 {: .note }
 > ✅ **Validated against Unraid 7.2.3** - All properties verified against `/var/local/emhttp/var.ini` on live systems.
+>
+> See the [DocTest validation plugin](https://github.com/mstrhakr/unraid-plugin-docs/blob/main/validation/plugin/source/emhttp/DocTest.page) for a working example that displays `$var` array values.
 
 ## Overview
 
@@ -73,7 +75,7 @@ This file is continuously updated by the Unraid system to reflect current state.
 | `mdResync` | string | Resync position (if active) | Block number |
 | `mdResyncSize` | string | Total resync size | Block count |
 | `mdResyncAction` | string | Resync action type | `"check"`, `"rebuild"`, `"sync"` |
-| `mdNumStripes` | string | Number of stripes | `"1280"` |
+| `md_num_stripes` | string | Number of stripes | `"1280"` |
 | `mdNumDisks` | string | Number of array disks | `"4"` |
 | `mdNumDisabled` | string | Number of disabled disks | `"0"` |
 | `mdNumMissing` | string | Number of missing disks | `"0"` |

validation/results/unraid-7.2.3.md

@@ -11,9 +11,9 @@
 |----------|--------|--------|-------|
 | Event System | 16 | 0 | All 16 documented events validated |
 | File Paths | 19 | 1 | Docker socket may not exist if Docker disabled |
-| $var Array | 31 | 1 | `mdNumStripes` uses different key name |
+| $var Array | 32 | 0 | All properties validated (mdNumStripes → md_num_stripes fixed) |
 | PHP Functions | 7 | 0 | All functions found |
-| **Total** | **73** | **2** | 97.3% pass rate |
+| **Total** | **74** | **1** | 98.7% pass rate |
 
 ## Event System Validation