Cell Configuration
To get the best of RUNME, and to offer a fantastic README experience, RUNME has a cell configuration option which allows you to indicate how the cell will be executed.
Configure Cell's Execution
Not all commands are equal, and expectations of how execution works can differ! For example, code blocks can be to be:
- File-watchers for compilers & bundlers should run as background tasks
- Executors for Interactive and Non-interactive programs & scripts
- Human-centric output: JSON, text, images, etc
- Terminal visibility when no errors occur
Just click "Configure" on the respective cell to make modifications to the cell execution behavior:
If you feel more comfortable editing the markdown file directly, you can do it by using the following configuration options schema:
```sh { interactive=false name=echo-hello-world }
echo hello world ```
Try out the previous command
echo hello world
The entire configuration schema as an example
```sh { interactive=true name=example mimeType=text/plain closeTerminalOnSuccess=false background=false }
echo hello world ```
Sidenote
Take a look at more examples available inside the VS Code extension repo for a reference on how to apply these code block attributes in different use cases!
Specify Language in Blocks
Runme, just like most Markdown viewers, will work best when a script's language is contained inside of fenced code blocks.
If possible, always specify the language according to the markdown standard as is illustrated below:
```sh
$ echo "language identifier in fenced code block"
```
Warning!
Out of the box, Runme will leverage the Guesslang ML/AI model with a bias towards Shell to detect the languages for unidentified code blocks.
While this works well in a lot of cases, the accuracy is not perfect.
Handle long-running processes
It is very common to use file-watcher enabled compilers/bundlers (npm start dev
, watchexec...
etc) in the background during development.
For any cell containing an instance of these commands be sure to tick the "background" cell setting. This will prevent execution from permanently blocking the notebook UX.
Once ticked notice the "Background Task" label shows up in the cell status bar!
Default: false
Example
```sh { background=true }
npm run watch
```
Interactive vs non-interactive cells
If a cell's commands do not require any input from a reader it might be a good fit to include the cell's output inside the notebook. This is useful if the resulting output could be useful as input in a downstream cell. This is what interactive=false
is for, and it defaults to true.
Default: true
Example
```sh { interactive=false }
openssl rand -base64 32
```
Sidenote
Please note that the Runme team is currently working on making output in both notebook & terminal default behavior.
Terminal visibility post-execution
A cell's execution terminal is auto-hidden unless it fails. This default behavior can be overwritten if keeping the terminal open is in the interest of the Runme notebook reader. Just untick closeTerminalOnSuccess
(false
).
Default: true
Example
```sh { closeTerminalOnSuccess=false }
docker ps | grep runme/demo:latest
```
Human-friendly output
JSON, text, images, etc. Not all cells’ output is plain text. Using the mimeType
specifier it is possible to specify the expected output's type. Notebooks have a variety of renderers that will display them human friendly. The MIME type defaults to text/plain.
See below for the list of supported MIME types!
Configuration Option Reference
Configuration | Description | Default value |
---|---|---|
background | Indicates if the cell should be runned as a background process | false |
interactive | Indicates if run should allow interactive input | false |
closeTerminalOnSuccess | Hide Terminal after cell successful execution | true |
mimeType | Cell’s output content MIME type | text/plain |
name | Cell’s canonical name useful for referencing the cell via CLI | auto-generated |
promptEnv | Prompt user to set exported environment vars | true |
Supported MIME types
Runme supports the standard VS Code MIME types alongside custom Runme MIME types.
Standard VS Code MIME types
- text/plain
- application/javascript
- text/html
- image/svg+xml
- text/markdown
- image/png
- image/jpeg
MIME types for rendering code
- text/x-json
- text/x-javascript
- text/x-html
- text/x-rust
- text/x-LANGUAGE_ID for any other built-in or installed languages.