Merge pull request #222 from dockersamples/os-conditional-blocks

Add OS-conditional support to conditionalDisplay directive

Author: mikesir87

components/interface/client/src/components/WorkshopPanel/markdown/ConditionalDisplay.jsx

@@ -1,18 +1,36 @@
 import { useVariables } from "../../../WorkshopContext";
 import { useMemo } from "react";
+import { detectOs } from "./detectOs";
 
 /**
- * This custom markdown directive provides the ability to conditionally show content based on variable values.
+ * This custom markdown directive provides the ability to conditionally show content based on variable values
+ * or the detected operating system of the user's browser.
  *
- * Usage example:
- * :::conditionalDisplay{variable="variable" requiredValue="value to match"}
- * Content to conditionally display goes here.
- * :::
+ * Usage examples:
+ *
+ *   :::conditionalDisplay{variable="variable" requiredValue="value to match"}
+ *   Content to conditionally display goes here.
+ *   :::
+ *
+ *   :::conditionalDisplay{os="mac,linux"}
+ *   Content shown to Mac and Linux users.
+ *   :::
+ *
+ *   :::conditionalDisplay{os="unix"}
+ *   Equivalent shorthand for mac + linux.
+ *   :::
+ *
+ *   :::conditionalDisplay{os="windows"}
+ *   Content shown to Windows users.
+ *   :::
  *
  * The following props can be used to control the display logic:
  *   - `requiredValue`: the value to match
  *   - `hasValue`: if set, the content will be shown if the variable has any value
  *   - `hasNoValue`: if set, the content will be shown if the variable is undefined or empty
+ *   - `os`: comma-separated list of operating systems (`mac`, `linux`, `windows`, or alias `unix` = mac+linux)
+ *
+ * When both `variable` and `os` are set, both conditions must be satisfied for content to render.
  *
  * @returns
  */
@@ -22,20 +40,38 @@ export function ConditionalDisplay({
   requiredValue,
   hasValue,
   hasNoValue,
-  ...rest
+  os,
 }) {
   const { variables } = useVariables();
-  const currentValue = variables[variable] || undefined;
+  const currentValue = variable ? variables[variable] || undefined : undefined;
 
   const shouldDisplay = useMemo(() => {
+    if (os !== undefined) {
+      const allowed = new Set(
+        String(os)
+          .split(",")
+          .flatMap((token) => {
+            const t = token.trim().toLowerCase();
+            if (!t) return [];
+            if (t === "unix") return ["mac", "linux"];
+            return [t];
+          }),
+      );
+      if (!allowed.has(detectOs())) return false;
+    }
+
+    if (variable === undefined) {
+      return os !== undefined;
+    }
+
     if (hasValue !== undefined) {
       return currentValue !== undefined && currentValue !== "";
     }
     if (hasNoValue !== undefined) {
       return currentValue === undefined || currentValue === "";
     }
     return currentValue === requiredValue;
-  }, [currentValue, variable, requiredValue, hasValue]);
+  }, [currentValue, variable, requiredValue, hasValue, hasNoValue, os]);
 
   if (!shouldDisplay) {
     return null;

components/interface/client/src/components/WorkshopPanel/markdown/detectOs.js

@@ -0,0 +1,23 @@
+/**
+ * Detects the OS of the browser running the labspace interface.
+ *
+ * Prefers the modern `navigator.userAgentData.platform` when available,
+ * falling back to `navigator.platform` and finally `navigator.userAgent`.
+ *
+ * @returns {"mac" | "linux" | "windows" | "unknown"}
+ */
+export function detectOs() {
+  if (typeof navigator === "undefined") return "unknown";
+
+  const raw = (
+    navigator.userAgentData?.platform ||
+    navigator.platform ||
+    navigator.userAgent ||
+    ""
+  ).toLowerCase();
+
+  if (raw.includes("win")) return "windows";
+  if (raw.includes("mac") || raw.includes("darwin")) return "mac";
+  if (raw.includes("linux") || raw.includes("x11")) return "linux";
+  return "unknown";
+}

docs/markdown-options.md

@@ -184,6 +184,39 @@ For values, the following options are available:
 - `hasValue`: if set, the content will be shown if the variable has any value
 - `hasNoValue`: if set, the content will be shown if the variable is undefined or empty
 
+### OS-conditional displays
+
+The `:::conditionalDisplay` directive also supports filtering by the operating system of the user's browser using the `os` parameter. This is useful when commands must run natively on the user's machine and differ between platforms.
+
+Example:
+
+    :::conditionalDisplay{os="unix"}
+    On Mac/Linux, run:
+
+    ```bash
+    echo "Hello from a Unix-like shell"
+    ```
+    :::
+
+    :::conditionalDisplay{os="windows"}
+    On Windows, run:
+
+    ```powershell
+    Write-Host "Hello from PowerShell"
+    ```
+    :::
+
+Supported `os` values (comma-separated for multiple):
+
+- `mac` — macOS
+- `linux` — Linux
+- `windows` — Windows
+- `unix` — alias for `mac,linux`
+
+The `os` parameter can be combined with `variable`, `requiredValue`, `hasValue`, or `hasNoValue`. When both are present, the content is shown only if *both* the OS and variable conditions match.
+
+OS detection uses `navigator.userAgentData.platform` when available, falling back to `navigator.platform`. Detection happens in the user's browser, so the result reflects where the browser is running — which is what matters for commands meant to run natively on the user's machine.
+
 ### Labspace-defined variables
 
 To support easier maintenance for values that may need to be updated in multiple locations, variables can also be defined in the `labspace.yaml` file. 

sample-content-repo/labspace/04-variables.md

@@ -58,6 +58,26 @@ Variables can be used to support the conditional displaying of text.
     > It appears the conditional is set and this content is displayed!
     :::
 
+## OS-conditional display
+
+Content can also be filtered by the operating system the user is viewing from. This is useful for showing commands that run natively on the user's machine.
+
+:::conditionalDisplay{os="unix"}
+You appear to be on Mac or Linux. Try this:
+
+```bash
+echo "Hello from a Unix-like shell"
+```
+:::
+
+:::conditionalDisplay{os="windows"}
+You appear to be on Windows. Try this:
+
+```powershell
+Write-Host "Hello from PowerShell"
+```
+:::
+
 ## Default Labspace variables
 
 As a help to authors, variables can also be defined in the `labspace.yaml` file to reduce maintenance where a value may appear in multiple places throughout the writeup.