From 7afa05e80230be1bfdd5d185ce6a7bffc95811ad Mon Sep 17 00:00:00 2001
From: Justin Hiemstra <jhiemstra@wisc.edu>
Date: Tue, 28 Oct 2025 15:26:05 +0000
Subject: [PATCH] Add Example callout and stylized Terminal block for writing
 user docs

This adds two helpers I was tinkering with while writing user docs.
The first is an "example" callout that stylizes a block of text for
adding examples of how to do something.

The second is a stylized Terminal block that's a bit more friendly than
trying to triple backtick everything. I was especially annoyed by this
because I like angle brackets <> for denoting when users would have to
provide their own input, and those are colored incorrectly when you do
triple backticks with bash formatting.
---
 components/Callout.tsx  | 17 +++++++++++++++++
 components/Terminal.tsx | 25 +++++++++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 components/Callout.tsx
 create mode 100644 components/Terminal.tsx

diff --git a/components/Callout.tsx b/components/Callout.tsx
new file mode 100644
index 0000000..b760815
--- /dev/null
+++ b/components/Callout.tsx
@@ -0,0 +1,17 @@
+// Wrapper around Nextra Callout to add "example" type for user documentation
+import { Callout as NextraCallout } from 'nextra/components'
+
+type CalloutProps = React.ComponentProps<typeof NextraCallout> & {
+  type?: 'default' | 'info' | 'warning' | 'error' | 'success' | 'example'
+}
+
+export function Callout({ type, children, ...props }: CalloutProps) {
+  if (type === 'example') {
+    return (
+      <NextraCallout type="info" {...props}>
+        <strong>Example:</strong> {children}
+      </NextraCallout>
+    )
+  }
+  return <NextraCallout type={type as any} {...props}>{children}</NextraCallout>
+}
diff --git a/components/Terminal.tsx b/components/Terminal.tsx
new file mode 100644
index 0000000..a6f0499
--- /dev/null
+++ b/components/Terminal.tsx
@@ -0,0 +1,25 @@
+// Module to help create terminal-like code blocks in user documentation.
+import React from "react";
+
+// It'd be cool if we colored lines beginning with $ differently, but I wasn't
+// able to figure that out.
+export function Terminal({ children }) {
+  return (
+    <pre
+      style={{
+        background: "#222",
+        color: "#eee",
+        padding: "1em",
+        borderRadius: "6px",
+        fontSize: "1em",
+        overflowX: "auto",
+        margin: "1em 0",
+        // Not sure how to altogether avoid rendering links (example links in Terminal blocks are probably never
+        // real links), but this makes them non-clickable
+        pointerEvents: "none",
+      }}
+    >
+      <code style={{ whiteSpace: "pre-wrap" }}>{children}</code>
+    </pre>
+  );
+}