Runbook Notebook Extension

Provides a Jupyter-like notebook for Runbooks, allowing automation of Troubleshooting Guides (TSGs) with:

• 🏻‍💻 various scripting languages (Bash, Node.js, Python, etc.)
• 💲 shell execution

Demo

Features

• Markdown Cells: Rendered markdown content for documentation
• Code Cells: Execute arbitrary code in the terminal
  • Supports JavaScript (Node.js), Python, Bash, and other languages
  • Code is written to a temporary executable file with appropriate interpreters
  • File is executed and stdout/stderr are captured
  • Output appears in the cell's output area (standard notebook behavior)
  • Rich output rendering: Outputs containing markdown patterns are automatically rendered as markdown
    • Code blocks (triple backticks `````)
    • Headers (# ## ###)
    • Bullet points (- * +)
    • Bold text (**text**)
    • Horizontal rules (---)
    • Tables (| col | col |)
  • Error handling: Non-zero exit codes display as error outputs with proper styling
  • Cancellation support: Long-running executions can be cancelled (works for all supported languages including Bash, Python, and JavaScript)
  • Variable Substitution: Reference outputs from previous cells using {{variable}} syntax
  • File Inclusion: Include file content using {{path/to/file.md}} syntax (reads from workspace root)

Usage

1. Create a .md file for documentation
2. Use code blocks for executable content:
   • ````javascript` for JavaScript code (executed in terminal)
   • ````bash` for shell scripts
   • ````python` for Python code
3. (optional) Configure cell behavior using @options on the first line with language-appropriate comment syntax:
   • All code cells: # @options {"timeout": 30} - Set execution timeout in seconds (kills process after timeout)
   • Variable storage: # @options {"id": "variable_name"} - Store cell output for use in other cells
   • JavaScript: // @options {"node_args": ["--inspect"]} - Pass Node.js arguments (planned)
   • Python: # @options {"python_path": "/usr/bin/python3"} - Specify Python interpreter (planned)
   • Both JSON and JavaScript object notation supported: {"key": "value"} or {key: "value"}
4. Open the file with the Runbook Notebook view
5. Execute cells using the play buttons

Variable Substitution

Three types of variable substitution are supported:

• Markdown Table Variables: Define variables in a table under any ## VARIABLES heading

  ## Variables
  
  name | value | notes
  -|-|-
  API_KEY | abc123 | Production API key
  BASE_URL | https://api.example.com | API endpoint

  • Case-insensitive variable names and lookups
  • Multiple VARIABLES sections are merged (last definition before the cell wins)
  • Only variables from cells above the current cell are available
  • Extra columns (like notes) are ignored

• Cell Output Variables: {{variable_name}} - References output from cells with @options {"id": "variable_name"}

  • Dynamic values from executed cells
  • Takes priority over table variables

• File Inclusion: {{path/to/file.md}} - Includes content from files relative to workspace root

  • Content is included as-is without code block wrapping
  • Useful for including documentation, templates, or reference data

Priority Order: Cell outputs > Table variables > File inclusion

Example Runbooks

• Graph Runbook
• Sample Runbook
• Database Runbook
• System Analysis Runbook

Installation

1. Clone this repository
2. Run npm install in the runbook-example folder
3. Press F5 to launch extension development host
4. In the new window, open a .md file and use "Open as Notebook" from the toolbar

Requirements

• VS Code 1.104.2+

Limitations

• Currently supports JavaScript (Node.js), Python, Bash, and shell scripts with appropriate interpreters
• Additional languages can be added via configuration settings