DOCSEARCHbyAlgolia
Submit Docs

TutorialKit Documentation

repository·main·Indexed 20 days ago

https://github.com/stackblitz/tutorialkit

A framework by StackBlitz for creating interactive coding tutorials using the WebContainer API. It includes a CLI for scaffolding projects, a runtime for managing tutorial state via TutorialStore, an Astro integration (@tutorialkit/astro), and a VS Code extension for visual content management. Tutorials are structured hierarchically into parts, chapters, and lessons using Markdown or MDX.

Tokens
46.5K
Snippets
175
Records
217
Agent score
69%

What's inside TutorialKit

  1. Overview of TutorialKit

    main
    TutorialKit by StackBlitz is a tool designed to enable the creation of interactive coding tutorials. It is intended to help developers boost the adoption of frameworks, UI libraries, or design systems by providing an interactive learning experience.

  2. Overview of TutorialKit capabilities

    main

    TutorialKit is an open source tool designed to create interactive code tutorials for UI libraries or JavaScript frameworks. It abstracts away the implementation of the user interface and the underlying execution logic, providing a complete environment for learners.

    Key features include:

    • Code Editor: Includes syntax highlighting for code experimentation.
    • Live Dev Server Preview: Automatically updates as learners modify tutorial code.
    • Interactive Terminal: Provides a command-line interface within the tutorial.
    • 'Show me the answer': A built-in capability to reveal correct solutions to learners.
    • Educational Content: Allows for side-by-side display of instructional text and interactive code.
    • Framework Integration: Supports single-line imports of your specific framework or design system library.
    • Enterprise Ready: Capable of running behind VPNs for enterprise deployments out of the box.

  3. What is @tutorialkit/runtime?

    main

    The @tutorialkit/runtime package provides a high-level abstraction layer over the WebContainer API. It is designed to help developers build highly interactive tutorials by managing the relationship between tutorial content, the WebContainer environment, and application components.

    The core abstraction provided is the TutorialStore.

  4. Create learning resources with TutorialKit

    main
    TutorialKit is a framework designed to help you build interactive learning resources, such as tutorials and lessons. It provides the necessary tooling and UI components out of the box, allowing you to focus on creating content rather than building the underlying educational platform. You can use it to create resources for internal teams or open-source communities.

  5. Understand the TutorialKit User Interface components

    main

    The TutorialKit UI is composed of several functional areas designed for interactive learning:

    • Top Bar: Contains the tutorial logo and a dark/light mode toggle.
    • Top Navigation: Provides lesson navigation via arrow buttons and a breadcrumb menu. The breadcrumb displays the current path (e.g., Part 1 / Chapter 2 / Lesson 1) and opens a dropdown to jump to any lesson in the tutorial structure.
    • Bottom Navigation: Displays the titles of the previous and next lessons for quick navigation.
    • Description: Renders the lesson content (text, images, code snippets) defined in the lesson's content.md or content.mdx file.
    • Code Editor: An interactive environment where users solve challenges. It includes a file tree view, a Solve button to reveal the solution, and a Reset button to revert code to its initial state. Edits are automatically picked up by the Preview app's dev server.
    • Preview: Displays the running application resulting from the lesson's code template. It shows preparation progress (e.g., "Installing dependencies", "Starting HTTP server") before the application is ready. The preview updates in real-time as code changes or navigation occurs.
    • Terminal: Displays the output from the demo application's dev server.

  6. Understand the TutorialKit project structure

    main

    TutorialKit is built on top of Astro. The core content and configuration are organized as follows:

    • src/content/tutorial/: The directory where all tutorial content (parts, chapters, and lessons) resides.
    • src/templates/: Contains your custom templates.
    • theme.ts: Used to customize the visual theme of the tutorial.
    • uno.config.ts: Configuration for UnoCSS.
    • astro.config.mjs: Astro framework configuration.
    • public/: Contains static assets like favicon.svg and logo.svg (the default logo for the top left corner).

  7. Use the TutorialKit Code Extension features

    main

    The extension helps you manage courseware content without manually traversing the file system. Key features include:

    • Visual Navigation: View your tutorial's lessons, chapters, and parts in a dedicated side panel.
    • Content Creation: Create new lessons and chapters directly through the extension interface.
    • File Synchronization: When you navigate the visual tutorial structure in the side panel, the extension automatically focuses the corresponding folders and files in your VS Code file explorer, allowing for quick editing.

  8. Use @tutorialkit/astro for Astro projects

    main
    The @tutorialkit/astro integration allows you to use the TutorialKit tutorial format within an Astro project. It automatically adds the necessary routes to serve your tutorials and utilizes @tutorialkit/react to handle the dynamic components of the tutorial experience.

  9. Understand the UI Test structure

    main

    Test cases are located in the test directory. Each test file corresponds to a specific chapter, which in turn contains multiple lessons used for the test cases.

    Example directory mapping:

    • Navigation tests: test/navigation.test.ts tests lessons found in src/content/tutorial/tests/navigation/.
    • File Tree tests: test/file-tree.test.ts tests lessons found in src/content/tutorial/tests/file-tree/.

  10. Use TutorialStore to manage tutorial content

    main

    The TutorialStore is the central mechanism for managing tutorial content both within the WebContainer and across your application components.

    Important Lifecycle Rule: You should create only a single instance of TutorialStore in your application. Its lifetime must be bound to the lifetime of your WebContainer instance.

  11. Organize tutorial content with parts, chapters, and lessons

    main

    Tutorials are structured hierarchically. Content is organized into lessons, which are grouped into chapters, which are grouped into parts.

    Directory Hierarchy Example

    tutorial
├── 1-basics-of-vite
│   ├── 1-introduction
│   │   ├── 1-welcome
│   │   │   ├── content.md    # The actual lesson content
│   │   │   ├── _files        # Initial files provided to the user
│   │   │   └── _solution     # The solution files for the lesson
│   │   ├── 2-why-vite
│   │   │   ├── content.md
│   │   │   └── _files
│   │   └── meta.md           # Metadata for the chapter
│   └── meta.md               # Metadata for the part
├── 2-advanced
│   └── meta.md
└── meta.md                       # Metadata for the tutorial

    Lesson Components

    • content.md or content.mdx: The main body of the lesson.
    • _files/: A directory containing the initial state of the files the user works on.
    • _solution/: A directory containing the completed state of the files.
    • meta.md: A metadata file used for configuration (contains only Front Matter, no content).