Runme on VS Code
Runme strives to provide a great experience right out of the box. In this section we we will guide you through making the most of your markdown docs with Runme.
Install Runme VS Code extension
If you haven't already installed Runme for VS Code, please complete the steps in installation before proceeding.
Your First Runme
You can get started in one click with the following badge:
Simply follow the instructions provided by VS Code to get started in seconds:
Alternatively, clone into the Example Repo to follow along! This guide follows the
node-streams sub-package - simply open its README file and runme will do the rest.
If you want to use Runme outside VS Code, you can install the CLI standalone. Learn about the Runme CLI
Runme automatically converts all bash codeblocks in your README into runnable scripts. This makes getting started with a new project a breeze - say goodbye to annoying copy-and-pasting!
To run a script, click the Run button on its left-hand side. Start by running the first script under "Prerequisites":
As you can see, we have downloaded the
business_data.csv file, which contains business statistics about New Zealand in the years 2000-2021. It's a pretty big file!
For the set-up script to work, you'll need to have the
unzip utilities installed. The remaining scripts will also require
node.js to be installed. In a future version of Runme, we plan to provide a solution to help you manage these dependencies from within the notebook. Stay tuned!
Scroll down to the Examples section of the notebook. From there, try running Steps 1 and 2.
If everything goes right, you should get an output like the following:
Great! You can see the terminal output from each command beneath its respective cell. Our Node.JS script was able to parse that massive file with no problems!
Wondering how you know when a command is finished executing? Look out for the checkmark in the bottom left:
If the command fails, it will be an "X" mark instead!
Runme provides a handy "Copy" button to easily copy the output of a command!
Sometimes, the output of a command can clutter up the screen. To prevent this, use the "Clear Cell Outputs" menu option.
Alternatively, select the output and use the Option+Delete shortcut.
Congratulations on running your first Runme notebook! 🎉While you've understood the basics, there's more to discover about Runme's powerful features. Let's get ready to dive deeper.
Runme Editing & Authoring
Runme combines running, viewing, and editing into one experience.
Start by initializing a new project and adding a new
README.md file. Alternatively, you can select
Runme Notebook from the
File->New File menu. When you open it, you should get an empty canvas, like this:
To add a new Markdown section, click the "+ Markdown" button in the top left or center:
You can then edit the markdown block directly:
As shown in the image below, once you're done editing a block, use the Check icon (the one with the checkmark):
To edit the cell again, use the Edit Cell icon:
Finally, you can remove a cell at any time using the Delete Cell icon:
Note that the usual shortcuts (like
Ctrl + Z) work perfectly in this environment too!
You can use
Ctrl+Enter to quickly finish editing a cell.
You can use Enter on its own to start editing a selected cell.
You can also use
CMD+Delete to quickly remove a cell.
Code cell blocks work similarly to Markdown blocks, and can be edited/saved/deleted in the same way.
To create a new code block, use the + Code button in the top left or center:
You can then freely add runnable code:
By default, our script will run in “Interactive Mode”. This will run the script in a separate terminal window, rather than in the notebook itself.
As the name implies, the interactive mode is great for interactive scripts. Our script, however, prints output and has no interactivity whatsoever.
Wouldn’t it be great to see the output in the terminal?
If we just try to run this as it is, we will experience the following:
To fix this easily, we'll need to access the Configure foldout by clicking on the Configure button:
From here, we can easily disable interactive mode:
Our code block will now display its output exactly as below:
Frontmatter is a common occurrence in markdown documents. At the moment Runme won’t break your frontmatter, but we also haven’t yet implemented an interface for managing or editing it from within the notebook. Stay tuned!
Runme Settings for VS Code
In the VS Code settings, several configurable settings influence general Runme behavior and enable experimental functionality.
Suppose that you have a script that intends to run in the background (like a dev watcher). To simulate this, we'll use the script
You could run this like other scripts, however, Runme supports a special "Background" mode for these kinds of tasks. This mode gives special tools to help manage them!
You can enable Background mode in the same foldout you configured Interactive mode:
Background mode only works in tandem with Interactive mode!
Now, when you run the script, it will be part of a long-running terminal session:
As is demonstrated by the previous video, background tasks are delineated by the "Background Task" label:
Background Task also has a Stop Task button to end their execution long after starting:
Markdown Script Metadata
Configuration fields like
interactive are set using markdown's script metadata feature:
Be sure not to strip this data if you want to use it!
Useful Tips & Tricks
How to ensure Runme is working properly?
It’s easy. Open your project README file and see it is now opened as a Notebook file! Check that shell commands are now rendered as runnable blocks. That’s pretty nice. Finally, you’re seeing the future of running your README files now. We bet you won’t want to return to plain markdown viewers.
How to open a README file as a markdown file?
Sometimes, you will want to see the file as a regular markdown file, and you don’t need to disable or uninstall Runme. You can right-click on the file and pick one of the options displayed when clicking Open with. You can select the built-in text editor or markdown preview for such cases.
To help you navigate the Markdown files in your project, Runme adds a super handy Runme Notebooks panel. Clicking any markdown file will open it in your code editor view: