Authoring Guide · Features

Terminal Component

Interactive terminal simulation with auto-typing commands and outputs

Updated Jan 1, 2024 · 6 min read

Terminal Component

The Terminal component creates an interactive, animated terminal simulation that automatically types commands and displays outputs when readers reach the section. Perfect for demonstrating command-line workflows, installation steps, and CLI tutorials.

Overview

The Terminal component simulates a real terminal experience with:

  • Auto-typing: Commands type out character by character automatically
  • Command Output: Shows command responses after each command
  • Section-Aware: Starts typing when the reader scrolls to that section
  • Beautiful UI: GitHub-style terminal with macOS window controls
  • Multiple Commands: Supports sequences of commands with outputs

Features

  • ✅ Auto-Start: Begins typing when section comes into view
  • ✅ Character-by-Character: Realistic typing animation
  • ✅ Command Output: Shows responses after each command
  • ✅ Multiple Commands: Chain multiple commands in sequence
  • ✅ Customizable Prompt: Change the command prompt (default: $)
  • ✅ Customizable Title: Set a custom terminal window title
  • ✅ Restart Button: Readers can restart the animation
  • ✅ Theme-Aware: Beautiful dark theme matching GitHub's terminal style

Basic Usage

Simple Command

MDX Syntax:

Rendered Result:

Terminal
$▊

Multiple Commands

MDX Syntax:

Rendered Result:

Terminal
$▊

Component Props

Required Props

  • commands (array): Array of command objects
    • Each command object has:
      • command (string, required): The command to type
      • output (string, optional): The output to display after the command
      • delay (number, optional): Delay in milliseconds before showing output (default: 800ms)

Optional Props

  • prompt (string): Command prompt symbol (default: $)
  • title (string): Terminal window title (default: "Terminal")
  • autoStart (boolean): Auto-start when section is reached (default: true)

Examples

Installation Workflow

MDX Syntax:

Rendered Result:

Installation

Follow these steps to install the project:

Installation Terminal
$▊

Custom Prompt

MDX Syntax:

Rendered Result:

Remote Server
user@server:~$▊

Commands Without Output

MDX Syntax:

Rendered Result:

Terminal
$▊

Custom Delays

MDX Syntax:

Rendered Result:

Terminal
$▊

Complete Examples

Docker Setup

MDX Syntax:

Rendered Result:

Docker Setup

Docker Terminal
$▊

Git Workflow

MDX Syntax:

Rendered Result:

Git Workflow

Git Terminal
$▊

Node.js Setup

MDX Syntax:

Rendered Result:

Node.js Project Setup

Node.js Terminal
$▊

How It Works

Auto-Start Behavior

The terminal automatically starts typing when:

  1. The reader scrolls to the section containing the terminal
  2. The terminal comes into the viewport (center 80% of screen)
  3. The component detects it's visible using Intersection Observer

Typing Animation

  • Speed: Commands type at ~30ms per character (realistic typing speed)
  • Sequence: Each command types completely before showing output
  • Output Delay: After command finishes, waits 500ms then shows output
  • Next Command: Waits for the specified delay (default 800ms) before starting next command

Command Structure

Each command in the array can have:

  • command: The command text (required)
  • output: The output text (optional, can be empty string)
  • delay: Custom delay before next command (optional, default: 800ms)

Best Practices

1. Keep Commands Realistic

Use actual commands that readers would run:

2. Use Meaningful Outputs

Show realistic command outputs:

Group related commands together:

4. Use Custom Delays for Long Operations

For commands that take time, use longer delays:

5. Set Descriptive Titles

Use titles that describe what the terminal demonstrates:

Advanced Usage

Terminal in Tabbed Content

You can use terminals inside tabbed content:

MDX Syntax:

Terminal with Callouts

Combine terminals with callouts for context:

MDX Syntax:

Styling

The terminal uses a GitHub-style dark theme:

  • Background: Dark (#0d1117)
  • Header: Darker (#161b22) with macOS-style window controls
  • Text: Light gray (#c9d1d9)
  • Prompt: Blue (#58a6ff)
  • Output: Muted gray (#8b949e)
  • Cursor: Blinking blue cursor

Performance

  • Uses Intersection Observer for efficient scroll detection
  • Typing animation is optimized with proper cleanup
  • No performance impact on page load
  • Smooth animations even with many commands

Accessibility

  • Terminal is keyboard accessible
  • Restart button has proper ARIA labels
  • Text is readable with sufficient contrast
  • Monospace font ensures command readability

Troubleshooting

Terminal Not Starting

  • Check that autoStart is true (default)
  • Ensure the terminal is in the viewport
  • Verify commands array is not empty

Commands Not Typing

  • Check that commands array is properly formatted
  • Ensure each command has a command property
  • Verify there are no syntax errors in MDX

Output Not Showing

  • Check that output property exists (can be empty string)
  • Verify output text is properly formatted
  • Check for special characters that might need escaping

Next Steps