Skip to content
Create interactive coding tutorials

Configuration

You can configure the appearance and behavior of a TutorialKit lesson by setting up properties in the lesson’s frontmatter block.

Note on inheritance

Some options, like “title,” will naturally be unique for each lesson. For others, like “template,” the value might be the same across multiple lessons, chapters, or even an entire tutorial. That’s why we’ve made it possible to set some properties on a chapter, part, or tutorial level. We call these values inherited.

For instance, if you set template: "simple" for a given part, all chapters and lessons in this part will use the “simple” template.

It’s also possible to override inherited properties on a lower level. For example, if you set template: "simple" for a part, but template: "advanced" for a lesson, that specific lesson will use the “advanced” template.

Configuration location

  • In case of a lesson, set the configuration in the frontmatter of the content.md file.
  • For a chapter, part or the whole tutorial, set the configuration in the frontmatter of the meta.md file on the respective level.

Options reference

type

Defines the type of the metadata.

Required Values Inherited
yes 'part', 'chapter' or 'lesson' no
title

The title of the part, chapter, or lesson.

Required Type Inherited
yes string no
slug

Lets you customize the URL segment which is /:partSlug/:chapterSlug/:lessonSlug

Required Type Inherited
no string no
i18n

Lets you define alternative texts used in the UI. This is useful for localization.

Required Type Inherited
no I18nText yes

The I18nText type has the following shape:

type I18nText = {
  /**
   * Template for formatting a part. Variables: ${index} and ${title}.
   *
   * @default 'Part ${index}: ${title}'
   */
  partTemplate?: string,


  /**
   * Text of the edit page link.
   *
   * @default 'Edit this page'
   */
  editPageText?: string


  /**
   * Text of the WebContainer link.
   *
   * @default 'Powered by WebContainers'
   */
  webcontainerLinkText?: string,


  /**
   * Text shown when there are no previews or steps to show in the prepare environment section.
   *
   * @default 'Start WebContainer'
   */
  startWebContainerText?: string,


  /**
   * Text shown on the call to action button to start webcontainer when boot was blocked
   * due to memory restrictions.
   *
   * @default 'No preview to run nor steps to show'
   */
  noPreviewNorStepsText?: string,
}
focus

Defines which file should be opened in the code editor by default when lesson loads.

Required Type Inherited
no string yes
editor

Configure whether or not the editor should be rendered. If an object is provided with fileTree: false, only the file tree is hidden.

Required Type Inherited
no boolean | { fileTree: false } yes
previews

Configure which ports should be used for the previews allowing you to align the behavior with your demo application’s dev server setup. If not specified, the lowest port will be used.

Required Type Inherited
no Preview[] yes

The Preview type has the following shape:

type Preview =
    | number
    | string
    | [port: number, title: string]
    | [port: number, title: string, pathname: string]
    | { port: number, title: string, pathname?: string }

Example value:

previews:
  - 3000 # Preview is on :3000/
  - "3001/docs" # Preview is on :3001/docs/
  - [3002, "Dev Server"] # Preview is on :3002/. Displayed title is "Dev Server".
  - [3003, "Dev Server", "/docs"] # Preview is on :3003/docs/. Displayed title is "Dev Server".
  - { port: 3004, title: "Dev Server" } # Preview is on :3004/. Displayed title is "Dev Server".
  - { port: 3005, title: "Dev Server", pathname: "/docs" } # Preview is on :3005/docs/. Displayed title is "Dev Server".
mainCommand

The main command to be executed. This command will run after the prepareCommands.

Required Type Inherited
no Command yes

The Command type has the following shape:

type Command = string
    | [command: string, title: string]
    | { command: string, title: string }
prepareCommands

List of commands to execute sequentially. They are typically used to install dependencies or to run scripts.

Required Type Inherited
no Command[] yes

The Command type has the following shape:

type Command = string
    | [command: string, title: string]
    | { command: string, title: string }
terminal

Configures one or more terminals. TutorialKit provides two types of terminals: read-only, called output, and interactive, called terminal. Note, that there can be only one output terminal.

You can define which terminal panel will be active by default by specifying the activePanel value. The value is the given terminal’s position in the panels array. If you omit the activePanel property, the first panel will be the active one.

An interactive terminal will disable the output redirect syntax by default. For instance, you cannot create a file world.txt with the contents hello using the command echo hello > world.txt. The reason is that this could disrupt the lesson if a user overwrites certain files. To allow output redirection, you can change the behavior with the allowRedirects setting. You can define this setting either per panel or for all panels at once.

Additionally, you may not want users to run arbitrary commands. For example, if you are creating a lesson about vitest, you could specify that the only command the user can run is vitest by providing a list of allowCommands. Any other command executed by the user will be blocked. You can define the allowCommands setting either per panel or for all panels at once.

By default, in every new lesson terminals start a new session. If you want to keep the terminal session between lessons, you can specify the id property for a given terminal panel and keep the same id across lessons.

Required Type Inherited
no Terminal yes

The Terminal type has the following shape:

type Terminal = {
    panels: TerminalPanel[],
    activePanel?: number,
    allowRedirects?: boolean,
    allowCommands?: string[]
}


type TerminalPanel = TerminalType
    | [type: TerminalType, title: string]
    | { type: TerminalType, title?: string, id?: string, allowRedirects?: boolean, allowCommands?: boolean }


type TerminalType = 'terminal' | 'output'

Example value:

terminal:
  activePanel: 1
  panels:
    - ['output', 'Dev Server']
    - type: terminal
      id: 'cmds'
      title: 'Command Line'
      allowRedirects: true
      allowCommands:
        - ls
        - echo
autoReload

Navigating to a lesson that specifies autoReload will always reload the preview. This is typically only needed if your server does not support HMR.

Required Type Inherited
no boolean yes
template

Specifies which folder from the src/templates/ directory should be used as the basis for the code. See the “Code templates” guide for a detailed explainer.

Required Type Inherited
no string yes

Display a link in lesson for editing the page content. The value is a URL pattern where ${path} is replaced with the lesson’s location relative to the src/content/tutorial.

Required Type Inherited
no string|false yes 
editPageLink: https://github.com/stackblitz/tutorialkit/blob/main/packages/template/src/content/tutorial/${path}

The inherited value can be disabled in specific parts using false.

editPageLink: false

openInStackBlitz

Display a link for opening current lesson in StackBlitz.

Required Type Inherited
no OpenInStackBlitz yes

The OpenInStackBlitz type has the following shape:

type OpenInStackBlitz =
    | boolean
    | { projectTitle?: string, projectDescription?: string, projectTemplate?: TemplateType }


type TemplateType = "html" | "node" | "angular-cli" | "create-react-app" | "javascript" | "polymer" | "typescript" | "vue"