feat: enhance remark configuration with directive support (#347)

- Added `remark-directive` plugin to support custom directives in
markdown.
- Introduced a new function `directiveColonSafe` to handle directive
padding correctly.
- Updated `.remarkrc.mjs` and package files to include the new
dependency.
- Improved documentation formatting by ensuring proper indentation for
admonitions.

Before Submitting This PR, Please Ensure You Have Completed The
Following:

1. [ ] Are internal links to wiki documents using [relative file
links](https://docusaurus.io/docs/markdown-features/links)?
2. [ ] Are all new documentation files lowercase, with dash separated
names (ex. unraid-os.mdx)?
3. [ ] Are all assets (images, etc), located in an assets/ subfolder
next to the .md/mdx files?
4. [ ] Have you checked to ensure there aren't other open [Pull
Requests](../../../pulls) for the same update/change?
5. [ ] Is the build succeeding?


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- Documentation
- Standardized admonition formatting and spacing across many pages for
cleaner rendering.
- Removed or tightened outdated/redundant tips, warnings, and inline
guidance across security, licensing, FAQs, WOL, ZFS, VM guides, shares,
and Docker overview.
- Added clearer vDisk expansion guidance with guest-OS partition steps
and example commands.
- Added urgent data-recovery cautions warning against dangerous
operations (format/repair).
- Chores
- Improved markdown directive handling and updated formatting tooling
for more reliable docs processing.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: elibosley

.remarkrc.mjs

@@ -2,6 +2,7 @@
 import remarkFrontmatter from 'remark-frontmatter'
 import remarkGfm from 'remark-gfm'
 import remarkMdx from 'remark-mdx'
+import remarkDirective from 'remark-directive'
 import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
 import remarkLintListItemIndent from 'remark-lint-list-item-indent'
 import remarkLintOrderedListMarkerStyle from 'remark-lint-ordered-list-marker-style'
@@ -23,6 +24,8 @@ import jsxContentSpacing from './remark-jsx-spacing.js'
 const plugins = [
     // MDX support
     remarkMdx,
+    remarkDirective,
+    directiveColonSafe,
     remarkFrontmatter,
     remarkGfm,
 
@@ -79,3 +82,58 @@ const remarkConfig = {
 };
 
 export default remarkConfig
+
+function directiveColonSafe() {
+  const data = this.data()
+  const extensions = data.toMarkdownExtensions || (data.toMarkdownExtensions = [])
+
+  for (const extension of extensions) {
+    if (
+      extension &&
+      typeof extension === 'object' &&
+      'handlers' in extension &&
+      extension.handlers &&
+      'containerDirective' in extension.handlers &&
+      Array.isArray(extension.unsafe)
+    ) {
+      extension.unsafe = extension.unsafe.filter(
+        (rule) => rule.character !== ':'
+      )
+
+      wrapContainerDirectiveHandler(extension)
+    }
+  }
+
+  data.toMarkdownExtensions = extensions
+}
+
+function wrapContainerDirectiveHandler(extension) {
+  const {containerDirective} = extension.handlers
+
+  if (typeof containerDirective !== 'function') {
+    return
+  }
+
+  extension.handlers.containerDirective = function wrappedContainerDirective(
+    node,
+    parent,
+    state,
+    info
+  ) {
+    const previous = state.bulletLastUsed
+    state.bulletLastUsed = undefined
+
+    try {
+      const output = containerDirective(node, parent, state, info)
+      return collapseDirectivePadding(output)
+    } finally {
+      state.bulletLastUsed = previous
+    }
+  }
+}
+
+function collapseDirectivePadding(value) {
+  return value
+    .replace(/(^|\n)([ \t]*:::[^\n]*?)\n\n/g, '$1$2\n')
+    .replace(/\n\n([ \t]*:::)/g, '\n$1')
+}

docs/unraid-os/advanced-configurations/optimize-storage/zfs-storage.mdx

@@ -263,9 +263,7 @@ Unraid can import %%ZFS|zfs%% pools created on other platforms with minimal hass
   5. **Finish and start array:** Click **Done**, then start the %%array|array%%.
 
   :::info[Automatic detection]
-
   Unraid will automatically detect and import the %%ZFS|zfs%% pool. Support vdevs (like log, cache/L2ARC, special/dedup) are listed under **Subpools** in the %%WebGUI|web-gui%%. There is no need to add subpools separately after initiating the import. Unraid will automatically import them alongside the main data disks when all required drives are assigned.
-
   :::
 
   After importing, running a %%scrub|scrub%% is highly recommended to verify data integrity.

docs/unraid-os/getting-started/set-up-unraid/configure-your-array.mdx

@@ -46,15 +46,11 @@ Unraid OS uses drives for various purposes:
      To safeguard cached data, assign more than one device to the %%cache pool|cache-pool%%. A single device does not offer protection from data loss. %%Cache pools|cache-pool%% can be expanded on demand.
 
   :::warning
-
   SSD support is experimental in the %%array|array%%. Some SSDs may not perform well due to variations in %%TRIM/Discard|trim-discard%% implementation, which could lead to undesirable results. This does not apply to %%cache pools|cache-pool%%. [Learn more about filesystem options here](../../using-unraid-to/manage-storage/file-systems.mdx).
-
   :::
 
   :::note
-
   SSD-based pools are optimal for applications and virtual machines, leveraging SSD performance for faster interactions. [Learn more about running applications here](../../using-unraid-to/run-docker-containers/overview.mdx).
-
   :::
 
 </details>

docs/unraid-os/getting-started/set-up-unraid/deploy-and-configure-unraid-os.mdx

@@ -105,11 +105,9 @@ Before deploying Unraid OS, it's important to verify your system's BIOS and stor
   For further assistance, visit the [Unraid general support forum](https://forums.unraid.net/).
 
   :::important
-
   Many motherboards limit boot device selection to 12 hard drives. If your USB flash drive is recognized as a hard drive, you may not be able to boot from it after installing 12 physical hard drives. Configure the BIOS to treat the flash drive as a removable device whenever possible.
 
   If using an add-on HBA, you may be able to disable INT 13h support to prevent its connected drives from appearing in the bootable devices list, helping to stay within the 12-drive limit.
-
   :::
 
 </details>

docs/unraid-os/getting-started/what-is-unraid.mdx

@@ -112,9 +112,7 @@ Unraid features a [user-friendly web interface](./explore-the-user-interface/tou
   Docker containers allow you to run applications in isolated, lightweight environments without the overhead associated with %%virtual machines|vm%%. Unraid simplifies the use of Docker by providing access to thousands of pre-configured apps through [Docker Hub](https://hub.docker.com/) and [Community Applications](../using-unraid-to/run-docker-containers/community-applications.mdx). This containerized approach enables Unraid users to run multiple applications simultaneously without compatibility issues. It also helps keep the system organized by using self-contained application packages and makes it easy to enhance server capabilities through Docker's ecosystem.
 
   :::note
-
   For advanced Docker settings, check out [Run Docker Containers](../using-unraid-to/run-docker-containers/managing-and-customizing-containers.mdx).
-
   :::
 
 </details>
@@ -125,9 +123,7 @@ Unraid features a [user-friendly web interface](./explore-the-user-interface/tou
   Unraid functions as a virtualization host, using a %%hypervisor|hypervisor%% to securely allocate resources to virtualized guests. This allows you to run various applications in isolated environments, going beyond just network-attached storage.
 
   :::tip
-
   To use hardware virtualization in Unraid, ensure your CPU, chipset, BIOS, and device drivers are compatible. A full list of requirements is available in the [VM setup guide](../using-unraid-to/create-virtual-machines/overview-and-system-prep.mdx). If your server doesn't meet these requirements, the %%VMs|vm%% menu will be disabled in the Unraid %%WebGUI|web-gui%%.
-
   :::
 
   <details>
@@ -188,9 +184,7 @@ Unraid features a [user-friendly web interface](./explore-the-user-interface/tou
   For %%VM|vm%% setup steps, check out [Create virtual machines](../using-unraid-to/create-virtual-machines/overview-and-system-prep.mdx).
 
   :::caution
-
   %%GPU passthrough|gpu-passthrough%% requires compatible hardware (see [VM setup](../using-unraid-to/create-virtual-machines/vm-setup.mdx)).
-
   :::
 
 </details>

docs/unraid-os/system-administration/advanced-tools/command-line-interface.mdx

@@ -169,9 +169,7 @@ This command provides a real-time process and resource monitor.
   - Use arrow keys to scroll, and `k` to terminate processes.
 
   :::tip
-
   Consider using `htop` for a more user-friendly interface with enhanced controls.
-
   :::
 
 </details>
@@ -190,9 +188,7 @@ This command shows memory usage statistics.
   This displays RAM usage in a human-readable format. The `-h` flag means sizes will show in KB, MB, or GB instead of bytes.
 
   :::tip[Understand the output]
-
   A low "available" memory reading doesn’t necessarily indicate a problem—Linux aggressively caches data for performance.
-
   :::
 
 </details>

docs/unraid-os/system-administration/advanced-tools/wake-on-lan.mdx

@@ -80,16 +80,15 @@ The plugin manages most sleep configuration options.
      ```
 
   :::caution[Persistence]
-
   WoL settings configured manually are **not persistent** across reboots by default. To make them permanent:
 
   1. Create a `go` file on your flash drive at `/boot/config/go`.
+
   2. Add this line:
 
   ```
   /sbin/ethtool -s eth0 wol g
   ```
-
   :::
 
 </details>

docs/unraid-os/system-administration/maintain-and-update/changing-the-flash-device.mdx

@@ -53,11 +53,13 @@ For more guidance on selecting the best flash device for Unraid, check out [Spac
 - Avoid second-hand or previously used drives.
 - Test the new drive on your server before transferring your license.
 - Be cautious of counterfeit products, even from well-known brands.
-
 :::note
 
 The [forum announcement on counterfeit SanDisk drives](https://forums.unraid.net/topic/119052-psa-on-sandisk-usbs/) from January 2022 confirms SanDisk is not recommended due to counterfeit devices and manufacturing changes resulting in non-unique GUIDs. This affects both counterfeit and legitimate SanDisk drives.
 
+:::
+:::
+
 :::
 
 ---

docs/unraid-os/system-administration/secure-your-server/securing-your-connection.mdx

@@ -61,9 +61,7 @@ Below are the main ways to access your Unraid %%WebGUI|web-gui%%, depending on y
   5. Click **Apply**.
 
   :::warning
-
   Anyone on your network can intercept data sent over HTTP. Use HTTPS whenever possible.
-
   :::
 
 </details>
@@ -86,9 +84,7 @@ Below are the main ways to access your Unraid %%WebGUI|web-gui%%, depending on y
   5. Click **Apply**.
 
   :::important
-
   Browsers will show a certificate error. All traffic is still encrypted after you accept the warning.
-
   :::
 
 </details>
@@ -124,15 +120,11 @@ Below are the main ways to access your Unraid %%WebGUI|web-gui%%, depending on y
   - If you install the [Unraid Connect plugin](../../../unraid-connect/overview-and-setup.mdx), it will also be shown on the Connect dashboard.
 
   :::info
-
   The myunraid.net certificate is trusted by browsers and does not display warnings. The URL uses your LAN IP address with dots changed to dashes, plus a unique 40-character %%hash|hash%% assigned to your server.
-
   :::
 
   :::tip[Fallback access]
-
   If %%DNS|dns-name-resolution%% resolution becomes unavailable (e.g., your Internet goes down), you can use the local URLs with your server name or IP address as backup access methods.
-
   :::
 
 </details>
@@ -155,7 +147,6 @@ Below are the main ways to access your Unraid %%WebGUI|web-gui%%, depending on y
      If you install the [Unraid Connect plugin](../../../unraid-connect/overview-and-setup.mdx), it will also be shown on the Connect dashboard.
 
   :::caution
-
   If %%DNS|dns-name-resolution%% resolution becomes unavailable (e.g., your Internet connection goes down), you will not be able to access the %%WebGUI|web-gui%% using the Myunraid.net URL.
 
   To regain access:
@@ -164,7 +155,6 @@ Below are the main ways to access your Unraid %%WebGUI|web-gui%%, depending on y
   - Run `use_ssl no` to switch to HTTP (`http://[servername].[localTLD]` or `http://[ipaddress]`).
   - Run `use_ssl yes` to switch to HTTPS using a self-signed certificate (`https://[servername].[localTLD]` or `https://[ipaddress]`). See [HTTPS with a self-signed certificate](#https-with-self-signed-certificate) above for more details.
   - Once %%DNS|dns-name-resolution%% is restored, set **Use SSL/TLS** back to *Strict* for full security.
-
   :::
 
 </details>
@@ -177,10 +167,8 @@ When you access `http://[servername].[localTLD]`, the redirect behavior depends
 
 - **Strict**: You will be redirected to `https://[lan-ip].[hash].myunraid.net`.
   :::note
-
   This can make local access difficult if %%DNS|dns-name-resolution%% is unavailable. See the caution under [HTTPS with Myunraid.net certificate and with no fallback URL](#https-with-myunraidnet-certificate-and-with-no-fallback-url).
-
-:::
+  :::
 
 - **Yes**: You will be redirected to `https://[servername].[localTLD]`. This will still work even if your internet connection is down.
 
@@ -227,9 +215,7 @@ If your certificate is invalid or does not match the server's URL, Unraid will d
   7. Optionally, enable [Unraid Connect remote access](../../../unraid-connect/remote-access.mdx) for secure, browser-trusted remote management.
 
   :::tip
-
   For wildcard certificates, ensure the certificate's Subject Alternative Name or Subject field contains `*.[localTLD]` where `[localTLD]` is the exact value you entered in the **Local TLD** field in **Management Access**.
-
   :::
 
 </details>

docs/unraid-os/troubleshooting/common-issues/data-recovery.mdx

@@ -175,6 +175,7 @@ If you used %%Maintenance Mode|maintenance-mode%%, stop the array and restart it
 If a previously functional disk becomes unmountable, this usually indicates file system corruption, often caused by an unclean shutdown or write failure.
 
 :::danger[Critical action]
+
 Never format an unmountable disk through the %%WebGUI|web-gui%%! Formatting erases all data and updates %%parity|parity%%, making recovery impossible.
 
 :::
@@ -210,6 +211,7 @@ Here’s how to proceed:
    ```
 
 :::danger
+
 The `--repair` option is extremely dangerous and can cause further data loss. Always backup or image the disk first. Review [the documentation](https://btrfs.readthedocs.io/en/latest/btrfs-check.html) and consider seeking additional advice if you’re unsure.
 
 :::