microsoft/codetour
Codetour
Code Tour is a VS Code extension that enables the creation of interactive, step-by-step guided walkthroughs of a codebase. It serves as a tool for guided code documentation, mapping descriptive explanations directly to specific file lines and directories within the editor to assist with codebase onboarding and technical knowledge transfer.
The system distinguishes itself through the use of regular expression-based anchoring to maintain step stability across different versions of source code and the ability to export tours as portable files containing the necessary code context for playback without the original local repository. It further supports synchronization with version control through Git-based tour versioning and provides drift detection to identify when code changes break existing tour links.
The project covers a broad range of capabilities, including tour recording and design, a playback engine with gutter-based discovery, and the ability to embed interactive elements such as shell commands and editor function invocations. Walkthroughs are stored using JSON serialization and can be shared via remote links or managed through flexible disk-based storage strategies.
Features
- Architectural Onboarding - Provides an interactive tool for architectural onboarding to help developers understand project structural organization and flow.
- Code Walkthroughs - Provides an interactive system for mapping descriptions to specific file lines and directories within the editor.
- Synchronized Code Annotations - Implements a format for embedding sequential explanations and markers directly into a codebase for synchronized playback.
- Interactive Code Documentation - Integrates interactive tours and narrated code paths directly into the editor to replace static documentation.
- Portable Tour Bundles - Packages tour steps with source code content to enable playback without the original local repository.
- Technical Knowledge Transfer - Allows recording a sequence of code highlights and explanations to share implementation details with a team.
- VS Code Extensions - Implemented as a VS Code extension to provide recording and playback of guided codebase walkthroughs.
- Gutter Metadata Markers - Renders visual markers in the editor margin to link live code lines back to their corresponding tour steps.
- Software Architecture Education - Facilitates software architecture education by leading users through sequenced series of files and directories.
- Code-Stability Anchors - Matches code locations using regular expressions to maintain tour step stability across source versions.
- Standalone Tour Exports - Saves tours as standalone files or gists containing all necessary code context for offline playback.
- Tour Recording - Includes a feature to capture a sequence of file locations and descriptions to create interactive walkthroughs.
- Code-to-Step Linkage - Links tour steps to line numbers and regex patterns to maintain stability during code changes.
- User Onboarding Tours - Ships a playback engine that navigates users through a predefined series of files and code selections.
- Deep-Link Tour Launchers - Enables opening specific tours and jumping to particular steps using custom URI handlers.
- Remote Tour Publishing - Enables publishing tours to external locations via web links for remote launching.
- Tour Serialization Formats - Stores tour steps and metadata in portable JSON files for version control and sharing.
- Tour-Driven Command Triggers - Triggers editor functions or extension commands directly from tour step descriptions via custom URIs.
- Contributor Navigation Guides - Offers portable and versioned tours to help external contributors navigate large repositories quickly.
- Tour Anchor - Integrates with CI pipelines to identify when code changes have broken the links or context of existing tours.
- Tour-Code Version Synchronization - Associates tours with specific branches, commits, or tags to synchronize walkthroughs with code versions.
- Editor Gutter Components - Uses editor gutter components to display icons indicating lines that belong to a tour.
- Programmatic Tour Controllers - Provides a programmatic interface for external tools to record, play, and export guided tours.
- Context-Free Instructional Steps - Supports introductory or intermediate explanation steps that operate independently of any specific file.
- Explorer-Based Step Focus - Focuses tour steps on specific folders in the file explorer to provide architectural context.
- Interactive Tour Elements - Adds links, shell command triggers, and editor command execution to tour steps.
- Tour Invocation URIs - Handles custom protocol links to launch specific walkthroughs and jump to precise steps.
- Step-Based Navigation Managers - Provides a dedicated UI and shortcuts for coordinating progression through sequential walkthrough steps.
- Tour Lifecycle Events - Exposes programmatic hooks for external extensions to trigger tour lifecycles and subscribe to playback events.
- Curriculum Sequencing - Provides the ability to connect different tours to create a sequenced onboarding curriculum.
