Working with Snippets

Snippets allow you to spice up your instructions with opportunities for the user to interact with their project. They're especially useful in contents that contain only instructions (no code editor, terminal, or web browser).

For example, you can use snippets to create interactive documentation to explain a new concept, break down a larger content, or explain your software to a user.

Creating a Snippet

To add a snippet, first select the "Instructions" option in the left sidebar. Then click the New Block dropdown and select Snippet. You'll be presented with the snippet screen which lists all your snippets. From here you can select or update an existing snippet or create a new one.

There are several types of snippets, as described below.

Code Editor Snippet

A code editor snippet allows the user to edit (but not execute) some code.

File Path

The absolute path of the file you'd like to edit.

Auto Size

If enabled, the snippet height is set to the height of the code in the snippet. Defaults to enabled.

Editor Settings - Code Pattern

Supports a regex pattern. If the code snippets height is not big enough to show all the code at once, the code will be scrolled down so that this line is the first line shown in the snippet.

Editor Settings - Line Number

Supports a line number to scroll the snippet to. If the code snippets height is not big enough to show all the code at once, the code will be scrolled down so that this line is the first line shown in the snippet.

Executable Code Snippet

An executable code snippet allows the user to edit and execute some code.

File Path

The absolute path of the file you'd like to edit.

Terminal Settings - Auto Clear

If enabled, the terminal will be cleared before the command is run or the file contents are piped in. Defaults to enabled.

Terminal Settings - Starting Command

The command to start the snippet terminal with (e.g.python3). If provided, the snippet's file contents will be piped to the terminal. If left blank, the Runtime scripts will be used. Defaults to blank.

Editor Settings - Code Pattern

Supports a regex pattern. If the code snippets height is not big enough to show all the code at once, the code will be scrolled down so that this line is the first line shown in the snippet.

Editor Settings - Line Number

Supports a line number to scroll the snippet to. If the code snippets height is not big enough to show all the code at once, the code will be scrolled down so that this line is the first line shown in the snippet.

Terminal Snippet

A terminal snippet allows the user to interact with their project from the command line.

Starting Command

The command you would like to start the terminal with.

Web Browser Snippet

A web browser snippet snippet allows the user to see a specific URL.

Starting URL

The URL you would like to start the snippet with. The user can refresh this URL, but not change it.

Generic Snippet Settings

The following configuration values apply to all snippets.

Summary

The summary of the snippet. Not shown to users.

Instruction

Optionally, pick an instruction if you'd like the user to be provided a checkbox on the snippet footer to mark complete. If the instruction is marked complete by a snippet, it will be treated as complete throughout the rest of the content.

Height CSS

Provide a value for how high you'd like the snippet to be (e.g.200px).