diff --git a/docs/configuration/mime.md b/docs/configuration/mime.md index 5c2146c8..29ea12b1 100644 --- a/docs/configuration/mime.md +++ b/docs/configuration/mime.md @@ -6,7 +6,7 @@ title: Supported MIME types Runme supports the standard VS Code MIME types alongside custom Runme MIME types. -**Standard VS Code MIME types** +## Standard VS Code MIME types - text/plain - application/javascript @@ -16,7 +16,7 @@ Runme supports the standard VS Code MIME types alongside custom Runme MIME types - image/png - image/jpeg -**MIME types for rendering code** +## MIME types for rendering code - text/x-json - text/x-javascript diff --git a/docs/configuration/output-rendering.md b/docs/configuration/output-rendering.md index d3a8090e..664e5d37 100644 --- a/docs/configuration/output-rendering.md +++ b/docs/configuration/output-rendering.md @@ -1,21 +1,14 @@ ---- -runme: - id: 01J2E98VM6SX1VTPJ524RPCTK4 - version: v3 ---- - # Custom output rendering Navigating through a large amount of JSON data can be overwhelming. Runme makes this much easier by taking your data and transforming it into an organized format, which can be a tabular arrangement, a flat data grid, or a data summary. ## How It Works -Runme uses two specific features to render JSON Data into human-friendly output. +Runme uses two specific features to render JSON Data into human-friendly output: -These features are: +### Mime Type -- **Mime Type** - Multipurpose Internet Mail Extensions(MIME) types are a standard way of indicating a nature and format of a file. Runme has an advanced configuration that allows users to specify the data's [MIME type](/configuration/mime.md). +Multipurpose Internet Mail Extensions(MIME) types are a standard way of indicating a nature and format of a file. Runme has an advanced configuration that allows users to specify the data's [MIME type](/configuration/mime.md). In this guide, we will work with JSON data to specify that. @@ -23,9 +16,10 @@ In this guide, we will work with JSON data to specify that. However it is important to note that setting the `mimetype` is optional as Runme has an effective auto-detection that detects JSON/CSV files reliably. -- **Interactive Mode** - The Interactive mode is another feature of Runme that makes rendering JSON data into human-friendly output possible. By default, Runme allows your scripts to run in the interactive mode. This mode enables you to interact with scripts in the output terminal. - However, you must turn that off to render your JSON data successfully. This can be done with a single click. +### Interactive Mode + +The Interactive mode is another feature of Runme that makes rendering JSON data into human-friendly output possible. By default, Runme allows your scripts to run in the interactive mode. This mode enables you to interact with scripts in the output terminal. +However, you must turn that off to render your JSON data successfully. This can be done with a single click. ![interaction mode](/img/guide-page/runme-interaction.png) @@ -35,15 +29,15 @@ Now that we have explored how it works let’s discuss what you need to get star To get started with rendering your JSON data, ensure you have the following: -- **Install Runme** +### Install Runme Install the [Runme extension on VS Code](https://marketplace.visualstudio.com/items?itemName=stateful.runme) to enable you access the Runme Notebook on your code editor. You can also set Runme as your [default Markdown viewer](/installation/vscode#how-to-set-vs-code-as-your-default-markdown-viewer). -- **Install Data Table Renderers** +### Install Data Table Renderers Install [Data Table Renderers](https://marketplace.visualstudio.com/items?itemName=RandomFractalsInc.vscode-data-table) extension on VS Code. -- **Install Jq** +### Install Jq To install the JSON processor, jq using brew, run the command below @@ -55,11 +49,11 @@ brew install jq This section will explore the step-by-step process of executing JSON data rendering with Bash script. -**Step One** +### Step One The first step is to create a `.json` file containing the JSON data to be rendered. Next, create a new `README.md` file. -**Step Two** +### Step Two In your `README.md` file, enter the command below into your Runme cell. @@ -73,16 +67,13 @@ Now, click the `configuration icon` to configure your cell. In the general confi Next, navigate to the advanced dashboard and enter the MIME type for your file, which is `application/json`. One good thing about Runme is that if you ignore this setting of your MIME type, Runme can automatically detect the file type and fill it in for you. -**Step Three** +### Step Three Click on the `run icon` to run the command and watch how your JSON data gets rendered into a human-friendly output. -Here is an example of the output that was obtained. - -IMAGES -**Step Four** +### Step Four -If you would love to explore other output types, you only need to click the menu icon (three vertical dots) beside your output. +If you want to explore other output types, you only need to click the menu icon (three vertical dots) beside your output. ![JSON output](/img/guide-page/runme-terminal-data-rendering.png) @@ -97,14 +88,11 @@ A small dashboard with several options will pop up. Carry out these actions: -Another great functionality is that you can download your data as a CSV or JSON when you select the `Flat Data Grid` presentation option, as shown in the image below. +
+You can also download your data as a CSV or JSON when you select the `Flat Data Grid` presentation option, as shown in the image below. ![JSON output save](/img/guide-page/runme-save-json-output.jpg) -## Feedback and Contribution - -We are still developing more features for Runme. If you have feedback on this or new ideas for improving this feature, feel free to [contact us](https://github.com/stateful/runme?tab=readme-ov-file#feedback). - ## Additional Resources See more resources on the Runme Renderer feature: diff --git a/docs/installation/cli.md b/docs/installation/cli.md index d9230333..b64d0198 100644 --- a/docs/installation/cli.md +++ b/docs/installation/cli.md @@ -5,29 +5,27 @@ title: Install the CLI # Install the CLI -Runme works effectively on the CLI. If you are a power user who enjoys running Markdown files from the terminal of your local machine, this section is for you. +The Runme CLI gives you much of the functionality available with the Notebooks, but from your terminal. ![cli](/img/terminal.png) -Here, we will give you detailed instructions on how to install Runme on your CLI. - -## Install Runme On MacOS +## Install Runme CLI on MacOS To get started, one of the easiest ways to install Runme on MacOS is by using [Homebrew.](https://brew.sh/) -Before you proceed, ensure you have the latest version of Homebrew on your local machine, use the command below to update if needed: +Ensure you have the latest version of Homebrew on your local machine, update if needed: ```sh {"id":"01HMXXFJFXWEN7ER7PSYKQNH3C","name":"brew update"} brew update ``` -Once you have the latest version of Homebrew, proceed with installing Runme. Use the command below to install: +Install Runme: ```sh {"id":"01HMXXF11NA3BJNCDYQAED3654"} brew install runme ``` -You should see a similar output if Runme is successfully installed. +The output should look something like: ```sh {"id":"01HQK3K4B8AC82PPT9370P49FD"} ==> Downloading https://ghcr.io/v2/homebrew/core/runme/manifests/3.0.2 @@ -46,11 +44,11 @@ Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP. Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`). ``` -## Installing Runme On Windows +## Installing the Runme CLI on Windows Windows users can also conveniently install Runme using any of the two options. -- Windows Subsystem for Linux 2 (WSL 2) or +- [Windows Subsystem for Linux 2 (WSL 2)](https://learn.microsoft.com/en-us/windows/wsl/) or - [Scoop.sh](https://scoop.sh/) a command-line installer for Windows ### Installing Runme on Windows Using Windows Subsystem for Linux 2 @@ -59,7 +57,7 @@ Runme is currently available only on the Cloud-native Shell Kernel, which makes To install the Runme CLI on your WSL server, follow these steps: -- **Install WSL** +### Install WSL Run the command below to install WSL on your Windows machine: @@ -67,7 +65,7 @@ Run the command below to install WSL on your Windows machine: wsl --install ``` -- **Connect to WSL** +### Connect to WSL Next, connect your machine to WSL, run the command below: @@ -77,7 +75,9 @@ wsl This will connect your machine to your WSL server. -- **Install Runme CLI** +Learn more about using our Windows Prereqs docs, [WSL 2 with Runme on Windows](/installation/windows) + +### Install Runme CLI After successfully connecting to the WSL server, you should install Runme CLI on your remote server. @@ -87,20 +87,18 @@ After successfully connecting to the WSL server, you should install Runme CLI on brew install runme ``` -While Homebrew provides an easy way to install Runme using the `brew command`, you can also conveniently install Runme using other platforms, such as `curl` and `wget`, regardless of your operating system. See the “Installing Runme Binary” section. +While Homebrew provides an easy way to install Runme using the `brew command`, you can also conveniently install Runme using other platforms, such as `curl` and `wget`, regardless of your operating system. See the [Installing Runme Binary](/installation/cli#installing-runme-binary) section. ### Installing Runme on Windows Using Scoop.sh -With Scoop, you can quickly install and set up your Runme CLI on your Windows machine. - -Run the commands below on your terminal to install Runme: +Run the commands below on your terminal to install Runme with Scoop: ```bash {"id":"01J58R4TJ430708WYDMXQ6D5FN"} scoop bucket add stateful https://github.com/stateful/scoop-bucket.git scoop install stateful/runme ``` -## Installing Runme Binary +## Installing from Runme Binaries Alternatively, you can explore Runme's [releases](https://github.com/stateful/runme/releases) and choose the binary that corresponds to your operating system. @@ -226,7 +224,5 @@ Runme’s TUI is awesome however, if you want to run a specific command quickly, You have successfully installed Runme on your CLI. Now, it’s time to explore just how Runme works on CLI and how you can leverage it for your Markdown files right in your MacOS or Windows terminal -**Additional resources:** - -- To learn more about how Runme works in CLI, read [our documentation.](/getting-started/cli) -- We have provided information on creating a Runme runbook on your Windows machine. Check out the [How Runme works on Windows](/installation/windows) guide. +- For more info check out the [Runme on Windows](/installation/windows) guide +- Read the CLI [Getting Started](/getting-started/cli) to learn about all it's features diff --git a/docs/installation/windows.md b/docs/installation/windows.md index 333fb261..b8db7b2a 100644 --- a/docs/installation/windows.md +++ b/docs/installation/windows.md @@ -5,23 +5,21 @@ title: Windows Prerequisites # Windows Prerequisites -To use Runme on a Windows machine, you have to use the Windows Subsystem for Linux 2 (WSL 2). Currently, Runme is built on Cloud-native Shell Kernel with a notebook, editor, terminal, and CLI interface, With WSL 2 you can get the full Runme exprience on your Windows machine. WSL 2 allows you to run a full Linux kernel inside a lightweight utility virtual machine (VM) on Windows 10 and Windows 11. +To use Runme on a Windows machine, you have to use the Windows Subsystem for Linux 2 (WSL 2). Currently, Runme is built on Cloud-native Shell Kernel with a notebook, editor, terminal, and CLI interface. WSL 2 makes it possible for Windows users to access the full Runme feature-set by running a full Linux kernel inside a lightweight utility virtual machine (VM) on Windows 10 and Windows 11. In this section, we will explore the various steps required to get Runme working on your Windows machine. ## Requirements -To get started, you need to : +To get started, you need to: - Set up the [Windows Subsystem for Linux](https://learn.microsoft.com/windows/wsl/install) and choose your preferred Linux distribution. - Ensure you have [Visual Studio Code](https://code.visualstudio.com/) installed on the Windows side rather than within WSL. - Install the [WSL extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) in your VS Code editor. -Once all the requirements are fulfilled, the next thing you need to do is start your WSL. To learn all about starting WSL, check out [this article.](https://learn.microsoft.com/en-us/windows/wsl/install) +Once all the requirements are fulfilled, start your WSL by [following this article.](https://learn.microsoft.com/en-us/windows/wsl/install) -## How to Install Runme Extension on VS Code on Windows - -In this section, we will provide a step-by-step guide to help you install the Runme VS Code extension on your Windows machine. +## Install the Runme Extension To get Runme installed in VS Code on your Windows machine, follow the steps below: @@ -38,11 +36,9 @@ To get Runme installed in VS Code on your Windows machine, follow the steps belo ## Setting up Runme on WSL -At this point, you should have WSL set up on your local Windows machine. As stated earlier, Runme is built on Cloud-native Shell Kernel. WSL helps you get the full experience of Runme on your Windows machine. - -To set up Runme on WSL, follow the steps below: +To set up Runme with WSL in VS Code, follow the steps below: -### Step One +### Connect to WSL In your VS Code, press `F1`. This will open up a dashboard containing a list of configuration/setup options. Select **Connect to WSL**. @@ -52,19 +48,19 @@ Alternatively, you can click on the button at the bottom left side of your VS Co ![vs code dashboard](/img/how-runme-works/runme-wsl-vscode-windows.png) -### Step Two +### Use Runme After connecting to your server using WSL, the next step is to install the Runme extension on the remote server so you can use it as you like. ![wsl windows](/img/how-runme-works/runme-install-wsl-windows.png) -### Step Three +### Choose a distro Use the File menu to open your folder. If you already have a folder open, you can also use the **WSL: Reopen Folder in WSL** command. You will be prompted which “Distro" to use. -## Running Runme works on Windows +## Verifying that it worked -This section will explore how [Runme works in VS Code on Windows](https://docs.runme.dev/how-runme-works/vscode). +Bringing it all together, you should now be able to run a command and verify that it's executing within WSL. - Create a Markdown file and click the “+Code” button to create a code cell for your scripts or command. @@ -80,7 +76,7 @@ This section will explore how [Runme works in VS Code on Windows](https://docs.r ## Runme CLI with WSL -You can also access Runme from your CLI with WSL on your Windows machine. To use the Runme CLI on your WSL server, follow these steps: +You can also access Runme from your CLI with WSL on your Windows machine by following these steps: ### 1. Connect to WSL @@ -92,7 +88,7 @@ wsl This will connect your machine to your WSL server. -### 2. Install Runme CLI +### 2. Install the Runme CLI After successfully connecting to the WSL server, the next step is to install Runme CLI on your local machine. @@ -104,7 +100,7 @@ brew install runme ### 3. Run tasks -At this point, you have connected to the WSL server and installed Runme CLI. You can run any task of your choice within your CLI. To do this, use `runme ` to execute tasks defined in the Markdown `.md` files. +You can run any task of your choice within your CLI. To do this, use `runme ` to execute tasks defined in the Markdown `.md` files. ![runme cli](/img/how-runme-works/runme-cli-windows.png) diff --git a/docs/resources/faq.md b/docs/resources/faq.md index cf5a79e8..4ab1ba9b 100644 --- a/docs/resources/faq.md +++ b/docs/resources/faq.md @@ -4,39 +4,40 @@ title: FAQ # Frequently Asked Questions -## **Runme and Stateful** +## Runme and Stateful -Runme was developed by the venture-backed company Stateful, Inc. Runme was built as an open source technology to to tackle the persistent issues of bitrot and outdated developer and operator documentation. Runme serves as an effective platform for running interactive runbooks in Markdown files, supporting scripting and pipelines. We believe in open-source software and intend for Runme to continue to be offered as such to deliver a powerful solution to the community. +Runme was developed by the venture-backed company Stateful, Inc. Runme was built as an open source technology to tackle the persistent issues of bitrot and outdated developer and operator documentation. Runme serves as an effective platform for running interactive runbooks in Markdown files, supporting scripting and pipelines. We believe in open-source software and intend for Runme to continue to be offered as such to deliver a powerful solution to the community. -## **Does Runme work with other notebook formats?** +## Does Runme work with other notebook formats? Currently, we are focused on using Markdown, which is widely used for documentation in various technologies. Runme stores configuration in a way that's like a more advanced version of Markdown. This means your files will still work with regular Markdown tools. While we do not have specific plans yet, we might create tools to help move from other notebook formats to Runme. This could be handy for teams trying to bring everything together and use open standards. -## **How do you plan to make money with Runme? Will you introduce paid enterprise or support plans, or consider monetizing user data?** +## How do you plan to make money with Runme? Will you introduce paid enterprise or support plans, or consider monetizing user data? Currently, we do not have specific plans to charge for Runme as it's available under the open-source APL-2.0 license. Stateful, Inc., the company behind Runme, is initially focusing on building open technology to tackle issues with outdated developer documentation. We're committed to keeping Runme as an open-source solution, delivering powerful features to the community. Our goal is to create a community around addressing documentation challenges and maintaining a trusted relationship with our users. We want to assure you that we won't monetize or sell users' data under any circumstances. Potential monetization opportunities may arise from providing additional value in terms of team collaboration, discoverability, or auditing features for companies using Runme with internal repositories. The core functionality of Runme, such as running runbooks, will remain available without the need for proprietary products from Runme, Stateful, or third parties. -## **What is Runme Default editor in VS Code?** +## What is Runme Default editor in VS Code? VS Code is one of Runme's client interfaces for running your Markdown files. To use Runme in VS Code, you need to install the Runme Extension, which allows you to create and manage interactive runbooks directly within your code editor. With this extension, you can perform a range of runbook operations, such as editing, saving output, creating and updating documents, selecting custom interpreters and supported languages, debugging, and more—all integrated into your VS Code environment. Once you have installed the Runme VS Code extension, every Markdown file in your code editor will automatically be displayed as a runbook. -## **What differentiates Runme from a common Jupyter Notebook?** +## What differentiates Runme from a common Jupyter Notebook? -Runme is quite different from the common Jupyter Notebook in both features, client integration, usage, etc., Here are a few features that sets Runme apart: -Runme should execute cells written in many programming languages out of the box (see supported languages) -Runme notebooks/runbooks are being stored in 100%-compatible Markdown -Runme kernel exposes services that produce consistent results regardless of what client (CLI, Extension, CI/CD) is being used -Runme aims to provide a great CLI and VS Code experience, including the web permutations -Runme fosters an ecosystem that aims to integrate with popular platforms & ISPs unlocking enhanced DX (workflow.yaml for example) -Runme is made for CI/CD (CLI/GH Action, docker images) to provide a test automation component to your development workflow +Runme is quite different from the common Jupyter Notebook in both features, client integration, usage, etc. Here are a few features that set Runme apart: -## **How Do I Share a Variable Between Cells in Runme?** +- Runme should execute cells written in many programming languages out of the box (see supported languages) +- Runme notebooks/runbooks are being stored in 100%-compatible Markdown +- Runme kernel exposes services that produce consistent results regardless of what client (CLI, Extension, CI/CD) is being used +- Runme aims to provide a great CLI and VS Code experience, including the web permutations +- Runme fosters an ecosystem that aims to integrate with popular platforms & ISPs, unlocking enhanced DX (workflow.yaml, for example) +- Runme is made for CI/CD (CLI/GH Action, docker images) to provide a test automation component to your development workflow + +## How Do I Share a Variable Between Cells in Runme? The non-block scope sharing feature in Runme prevents variables declared in one cell from being directly accessed in another cell. For instance, if you have two Python cells, you cannot declare a variable in one cell and use it in the other. However, we have a technique called "Piping," which is declared using $\_\_. This allows you to pass a variable declared in one cell to another cell within the same file. With this method, you can effectively share information between cells. -### **How to switch back from the Runme Notebook view to the Markdown text document?** +### How to switch back from the Runme Notebook view to the Markdown text document? You can easily switch between Runme's notebook UI and the standard Markdown text editing experience. Read more on that in the Runme UX documentation. diff --git a/docs/resources/walkthrough.md b/docs/resources/walkthrough.md index e1cbcf58..ef4caade 100644 --- a/docs/resources/walkthrough.md +++ b/docs/resources/walkthrough.md @@ -3,11 +3,11 @@ sidebar_position: 6 title: Walkthrough --- -# **Runme Walkthrough** +# Runme Walkthrough > 💡 This document is a self contained Runme Notebook which will guide you through Runme's key features. If you have _VS Code_ installed locally, you can open this document in Runme by clicking the _"Open with Runme"_ badge on **[docs.runme.dev](https://docs.runme.dev/)** which will open this document as a notebook locally. If you are already inside VS Code, you can skip over the next paragraph. -## **Clone the Repository** +## Clone the Repository ```sh {"id":"01HY0Y62WJCT2BVD5VA2HZ32TG"} git clone --depth=1 https://github.com/stateful/docs.runme.dev.git @@ -16,33 +16,33 @@ cd docs.runme.dev Unless you already have VS Code installed locally, go ahead and install the Runme CLI. Otherwise skip to the next paragraph please. -### **MacOS** +### MacOS ```sh {"cwd":"docs.runme.dev","id":"01HY0SZCMGA291TVE2R1QKNVX4"} brew install runme && runme open ``` -### **Linux & Windows** +### Linux & Windows ```sh {"cwd":"docs.runme.dev","id":"01HY0SZCMGA291TVE2R40BDNJ9"} npx runme open ``` -## **Runme by Example** +## Runme by Example -Let's quickly run through examples that best illustrate how Runme can unleash your docs and make them much more useful for everybody. +Let's quickly run through some examples: -> 🚨 Please be absolutely sure that you have cloned into the repository and opened the `docs/index.md` file in the notebook UI inside VS Code. Otherwise you will not be able to - literally - run the next steps. +> 🚨 Please be absolutely sure that you have cloned into the repository and opened the `docs/index.md` file in the notebook UI inside VS Code.
-After clicking the _"Open with Runme"_ badge or cloning into the repo what you see should resemble following screenshot. +After cloning into the repo you should see something similar to the follow screenshot: ![Runme in VS Code](/img/doc-in-vscode.png) -## **Generic Docs Using Prompts** +## Generic Docs Using Prompts -Write generic docs and notebooks using Runme's smart prompting. This is useful when you want to platform others. Per default, exported environment variables will trigger prompts for users to input values. If the export is declared without any quotes, Runme will prompt with the value as a message. With quoted values (no matter if single or double quotes), Runme will prompt with the value as a placeholder value for confirmation. +Create generic documentation and notebooks using Runme's smart prompting feature, which is helpful for enabling others to work on different platforms. By default, any exported environment variables will trigger prompts for users to input values. If the export is declared without quotes, Runme will display the value as a message in the prompt. If the export is enclosed in quotes (single or double), Runme will use the value as a placeholder, asking the user to confirm or modify it."
-Runme's prompting default is _"auto"_. It will not prompt again on re-runs if values are already known. Click _"Configure"_ on the cell, to switch **promptEnv** to **no** (never prompt; run as is) or **yes** (always prompt; overwrite previous values). Try it yourself... just click the play button. +Runme's default prompt setting is _"auto"_, meaning it won't prompt again on re-runs if the values are already known. To change this, click **"Configure"** on the cell and set `promptEnv` to `no` (never prompt; run as is) or `yes` (always prompt; overwrite previous values). + +Try it yourself—just click the play button! ```sh {"id":"01HY0Z7HSFFV7KHPX559SNVSHN","terminalRows":"4"} export PROJECT_NAME=[Enter your project id] @@ -64,7 +66,7 @@ echo "CLUSTER_ZONE set to $CLUSTER_ZONE" You can reset all environment variables using the **Reset Session** button in the top bar or choose _"Execute and always prompt for input"_ from the caret menu next to the play button. Learn more [here](https://docs.runme.dev/configuration/cell-level#set-environment-variables). -## **Piping and Referencing Cells** +## Piping and Referencing Cells Runme, unlike [Jupyter](https://jupyter.org/), does not allow block-scope variables and functions sharing. This means that variables declared in one cell are not per se available in another cell. However, Runme is aware of environment variables. As seen above, `export` variable declarations ulitmately will be stored in the environment. @@ -78,7 +80,7 @@ Outside of that, you can reference cells in two ways. This is particularly usefu
-### **1. Reference Last Cell Output** +### 1. Reference Last Cell Output The most recent cell output will be stored in a special environment variable called `$__` (double underscore). @@ -92,7 +94,7 @@ This is useful when you want to reference the output of the last cell. When `$__ echo -n "Previous cell's output was:\n\n$__" ``` -### **2. Reference by Cell Name** +### 2. Reference by Cell Name Notice how the cell above is named `FILE_LIST` (visible in notebook UI & [raw Markdown](https://raw.githubusercontent.com/stateful/docs.runme.dev/main/docs/index.md)). This allows you to reference the output of that cell by using the cell name as an environment variable. This makes reference outputs more robust since they no longer have to run back-to-back. However, sequence still matters. The referenced cells has to run first. diff --git a/docs/usage/auto-save.md b/docs/usage/auto-save.md index 0e48b077..93e4b2f2 100644 --- a/docs/usage/auto-save.md +++ b/docs/usage/auto-save.md @@ -2,11 +2,11 @@ title: Auto-Save session outputs --- -# **Auto-Save Auto-Save session outputs** +# Auto-Save Auto-Save session outputs The Runme auto-save feature efficiently saves and manages your commands and executed cells for future reference. When you run a command within your Runme Notebook, a Session Ouputs file is automatically generated. This captures a complete copy of the original Markdown document, along with the generated outputs, details on when each cell was run, the time it took to run the cell, and exit codes. You can also turn your command/generated outputs into a [Runme gist](/usage/runme-gist). -### **Enable Auto-Save** +## Enable Auto-Save - Toggle Auto-Save On/Off: @@ -20,7 +20,7 @@ If you would like to turn the auto-save off, you can simply use the toggle butto Alternatively, you can set autosave to the default setting. This way, you do not need to manually enable the feature whenever you want to use it. -### **Auto-save default** +### Auto-save default By default, auto-save is turned off, as indicated by the autosave button at the top bar displaying off. However, if you want to use the session output feature, you can toggle the feature (on) or (off) using the autosave button. @@ -37,7 +37,7 @@ Alternatively, you can change the settings to be permanently on by adjusting the This action configures the system to automatically save the output of each cell execution. -## **Session Outputs** +## Session Outputs Runme uses the session output feature to provide advanced auto-save functionality. When auto-save is enabled, Runme captures a complete copy of the original Markdown document and creates the entire Markdown file during the notebook’s execution. @@ -57,7 +57,7 @@ The session outputs are written per Runme session, which is saved throughout the If there are more forms you would like to be added to the session output, kindly [let us know](https://github.com/stateful/runme/issues/new). We are open to incorporating your requests. -### **Why Separate Session Outputs?** +### Why Separate Session Outputs? You might wonder why we have created a separate Session Outputs file instead of embedding outputs directly into the Markdown document. Here are some reasons: @@ -74,7 +74,7 @@ While we are contemplating the possibility of transparently opening Session Outp > It is strongly recommended that you do not deploy the session output files to your version control. You can `.gitignore` the files to ensure that it doesn't get deployed. -## **Additional Information** +## Additional Information The auto-save feature is also used in other Runme’s features. Some of these include: diff --git a/docs/usage/browser-launcher-extension.md b/docs/usage/browser-launcher-extension.md index 250b5b69..353e3950 100644 --- a/docs/usage/browser-launcher-extension.md +++ b/docs/usage/browser-launcher-extension.md @@ -1,6 +1,3 @@ ---- ---- - # Browser launcher extension If you like to quickly check out a GitHub project from your browser, you can use the Runme Web Extension. It is supported in all Chromium browsers (e.g. Chrome, Brave, or Opera) and Firefox. You can download the extension through: @@ -10,15 +7,15 @@ If you like to quickly check out a GitHub project from your browser, you can use The web extension adds Runme links to the following places: -### **Local Clone Section** +### Local Clone Section ![Runme Link in Local Clone Section](/img/web-extension/list.png) -### **Markdown Title Header** +### Markdown Title Header ![Runme Link in Markdown Title Header](/img/web-extension/markdown.png) -### **Code Sections** +### Code Sections ![Runme Link in Code Sections](/img/web-extension/code.png) diff --git a/docs/usage/devcontainers.md b/docs/usage/devcontainers.md index a484549c..62352aff 100644 --- a/docs/usage/devcontainers.md +++ b/docs/usage/devcontainers.md @@ -6,7 +6,7 @@ runme: # Runme in a DevContainer -## **Creating your development container** +## Creating your development container A development container, also known as a `DevContainer`, is a dockerized container that allows you to run your software in a fully configured development environment. This significantly speeds up application deployment and scalability. @@ -67,11 +67,11 @@ This will execute your Python app within the dev container. 1. Ensure Docker is open and running on your system before you create a Dev container. 2. You do not need to create a separate dockerfile for this as the base image and settings needed for your development environment are specified in the dev container configuration (`devcontainer.json`). This eliminates the need for explicit Dockerfile maintenance and makes it simple to share and replicate the development environment across several machines. -## **Setting up Runme on VSCode** +## Setting up Runme in VSCode Installing Runme in your VS Code is one of the various ways you can utilize the awesome features of Runme. To set up Runme on VS Code, follow our [installation guide.](/installation/vscode) -## **Running development tasks using Runme within your container** +## Running development tasks using Runme within your container Runme works perfectly  to automate processes and conduct development operations within the container . To run your code with Runme in your dev container, follow the steps below: @@ -106,13 +106,13 @@ You must take it back to a Runme setting to enable you to run your code with Run ![ouput](/img/guide-page/runme-terminal-devcontainer.png) -## **Other Features** +## Other Features Some other actions that can be performed in your Dev container include cloning repository, configuring container features, exploring a volume, etc. The image below shows you a non-exhaustive list of some of these actions. ![output dev container](/img/devcontainer-output.png) -## **Conclusion** +## Conclusion In this guide, we demonstrated how to create a dev container, set up Runme on VS Code, run development tasks using Runme within your container. diff --git a/docs/usage/embedded-github-action.md b/docs/usage/embedded-github-action.md index 5b6187c1..e9286780 100644 --- a/docs/usage/embedded-github-action.md +++ b/docs/usage/embedded-github-action.md @@ -15,7 +15,7 @@ GitHub Actions provides a robust CI/CD platform for automating development tasks -### **Workflow Types** +### Workflow Types - Events that occur in your workflow's repository - Events that occur outside of GitHub and trigger a repository_dispatch event on GitHub @@ -33,7 +33,7 @@ Currently, Runme only supports manual workflows; they are helpful to trigger job In general, being able to run a GitHub Action manually gives you control over workflows by adding an extra layer of flexibility to your CI/CD and automation processes. -### **How To Use It** +### How To Use It Use the **workflow_dispatch** event to specify your manually triggered workflow, you can optionally specify inputs that are passed to the workflow. The triggered workflow receives the inputs in the [inputs context](https://docs.github.com/en/actions/learn-github-actions/contexts#inputs-context) @@ -96,7 +96,7 @@ jobs: The above YAML file specifies a simple manual triggered workflow file with inputs: releaseVersion, releaseType, releaseChannel, publishMarketplace, publishOpenVSX, and a job that prints the values for each input in JSON format. -### **Use Runme To Trigger A Manual Workflow** +### Use Runme To Trigger A Manual Workflow Currently, there are two ways to indicate Runme to run a GitHub Action: diff --git a/docs/usage/pipes-variables.md b/docs/usage/pipes-variables.md index 7f0566f4..b23ce054 100644 --- a/docs/usage/pipes-variables.md +++ b/docs/usage/pipes-variables.md @@ -2,7 +2,7 @@ title: Pipes and variables --- -# **Usage of Piping and Variables** +# Usage of Piping and Variables Runme works a lot like a terminal, however, unlike Python's Jupyter it does not allow block-scope sharing of variables. Instead, you are encourage to use environment variables for inter-referencing of cells. Similar to how piping in and out of commands would work. Piping works in two ways. 1.) It's declared using `$__` to pass a variable declared in a previous execution to another cell or 2.) using a ENV variable. diff --git a/docs/usage/runme-gist.md b/docs/usage/runme-gist.md index 7bad3d5b..4d396f37 100644 --- a/docs/usage/runme-gist.md +++ b/docs/usage/runme-gist.md @@ -2,41 +2,42 @@ title: Runme Gist --- -# **Runme Gist** +# Runme Gist Would you like to share or store your plain texts or code snippets securely with others in your team without needing a full repository or document? Runme Gist makes this possible and prioritizes your information's sensitivity by keeping sensitive information secret. In this section, we will explain how you can use Runme Gist to generate gist and share your texts and code. -## **What is Runme Gist?** +## What is Runme Gist? Runme Gist combines [GitHub Gist](https://gist.github.com/) with Runme features to run, share, and store plain texts or code snippets in your Markdown file. What makes Runme Gist powerful is its ability to capture outputs and mask sensitive data without copying and pasting or integrating a third-party tool. All is done right within your Markdown file. -## **Installation** +## Installation To utilize the Runme Gist feature, set up the following Runme tools. - Install the [Runme extension](/installation/vscode) in your VS Code If you already have Runme installed in your VS Code, ensure you are upgraded to the latest version `v3.4.0`. - Set Runme as your [default Markdown viewer](/installation/vscode) to ensure all Markdown files in your code editor are automatically opened as a Runme notebook. -## **Setting Up Runme Gist** +## Setting Up Runme Gist As stated earlier, Runme Gist combines [GitHub Gist](https://gist.github.com/) with Runme features to enable you to securely run, share, and store code snippets. This section will explain how Runme Gist works using a step-by-step guide. -**Step 1: Open your Markdown File** +### Step 1: Open your Markdown File Create a `README.md` file and open it in your VS Code. If you already have the file you want to use, open it in VS Code. -**Step 2: Activate Auto-Save** +### Step 2: Activate Auto-Save + As part of the requirements to generate a gist, you need to activate the [auto-save feature](/usage/auto-save) of Runme. This ensures your outputs are saved automatically without manual intervention. ![runme gist Autosave ](/img/configuration-page/runme-gist-autosave.png) -**Step 3: Run Cells** +### Step 3: Run Cells Now, run your notebook cells. A separate file containing your saved output will be automatically generated, known as “Session Outputs.” -**Step 4: View Sessions Output** +### Step 4: View Sessions Output Session Output is a Runme feature that stores your generated cell outputs in a separate file so you can access them whenever necessary. See the [Session output](/usage/auto-save#session-outputs) guide. @@ -46,7 +47,7 @@ To view your Session Output, click “Sessions Outputs” to inspect the locally The Session Outputs feature is only available when the autosave is enabled and the Runme cell is run. -**Step 5: Toggle Between Mask and Unmask** +### Step 5: Toggle Between Mask and Unmask You can choose whether your Session Outputs should be masked or unmasked. Masking helps to keep your sensitive information secure. To keep your sensitive information secret, toggle the mask option; otherwise, choose the unmasked option. By default, Runme uses the open-source tool `data-guardian` to mask sensitive information on a best-effort basis. @@ -67,7 +68,7 @@ Alternatively, if you want to unmask only a particular session output, you can t ![Runme gist unmask](/img/configuration-page/runme-gist-unmask.png) -## **Creating and Managing Gist with Runme using Secret Gists** +## Creating and Managing Gist with Runme using Secret Gists GitHub Gist is a service provided by GitHub that allows users to share code snippets, notes, and other small pieces of text with others. Using two methods, you can push your Runme Session Output to GitHub Gist from your Markdown file with a single click. @@ -81,7 +82,7 @@ Runme will first prompt you to log into your GitHub account and grant write acce Lastly, use the Runme mask feature to keep your sensitive pieces secured. -## **Visual Representation of Runme Gist** +## Visual Representation of Runme Gist Here is a video that showcases how to generate Runme Gist for your entire Markdown file @@ -90,7 +91,7 @@ Here is a video that showcases how to generate Runme Gist for your entire Markdo -## **Generate Gist Per Cell** +## Generate Gist Per Cell Alternatively to generating Gist for the entire Markdown file, you can generate gist for each cell in your Markdown file. To do this, in your Session Outputs file, navigate to the cell you want to be generated as a gist and click on ‘Generate Gist’. diff --git a/docs/usage/shebang.md b/docs/usage/shebang.md index 8c927e54..512a2313 100644 --- a/docs/usage/shebang.md +++ b/docs/usage/shebang.md @@ -2,15 +2,15 @@ title: Shebang (running code) --- -# **Shebang Support** +# Shebang Support Shebang is a versatile tool designed to execute scripts written in various scripting languages including Shell, Perl, Python, and more. Runme integrates Shebang to enable users to run the script of their choice directly from the Markdown file in their preferred programming language. -## **Prerequisites** +## Prerequisites Before proceeding with the integration of Shebang in [Runme](/installation/cli), ensure that Runme is properly [installed](/installation/cli) on your system. This is a crucial step to guarantee the smooth execution of your runbooks -## **Run your Code with Runme in VS Code Using Shebang** +## Run your Code with Runme in VS Code Using Shebang Runme gives you the power to run your code right inside your Markdown file in VS Code without having to switch to a terminal. To do this, follow the steps below: @@ -19,7 +19,7 @@ Runme gives you the power to run your code right inside your Markdown file in VS 3. Click on the **Select Cell Language Mode** and select a language of your choice. 4. Now click on **Execute Cell** -## **Configuring Shebang Custom Interpreter in VS Code** +## Configuring Shebang Custom Interpreter in VS Code Before proceeding with the integration of Shebang in [Runme](/installation/cli), ensure that Runme is properly [installed](/installation/cli) on your system. This is a crucial step to guarantee the smooth execution of your runbooks @@ -46,13 +46,13 @@ runme ![shebang-output](/img/shebang-outputt.png) -## **Examples of Shebang Lines for Different Languages** +## Examples of Shebang Lines for Different Languages We have attached some scripts in various languages as seen below to enable you to test how Runme works in your VS Code. Each of the following examples, written in Python, Ruby, Bash, and Node.js (JavaScript), accomplishes the same task: they define a greeting ("_Hello, World!_"), obtain the current date and time, and then combine these into a single message. The primary difference lies in the syntax and functions/methods used for date and time formatting in each language. -### **Python** +### Python To run the Python code, you need to set the path to the Python interpreter, which is **_/usr/bin/python3_**, in the advanced section of your configuration in your code block. @@ -72,7 +72,7 @@ fullGreeting = greeting + " It's now " + currentDateTime print(fullGreeting) ``` -### **Bash** +### Bash To use Bash, you need to set the Interpreter to point to the Bash interpreter, which is **_/usr/bin/bash_**, in the advanced section of your configuration in your code block. @@ -91,7 +91,7 @@ fullGreeting="$greeting It's now $currentDateTime" echo $fullGreeting ``` -### **Ruby** +### Ruby To use Ruby, you need to add the path to the Ruby interpreter, which is **_/usr/bin/ruby_**, in the advanced section of your configuration in your code block. @@ -109,7 +109,7 @@ fullGreeting = "#{greeting} It's now #{currentDateTime}" puts fullGreeting ``` -### **PHP** +### PHP To use PHP, you need to add the path to the PHP interpreter, which is **_/usr/bin/php_**, in the advanced section of your configuration in your code block.. @@ -131,7 +131,7 @@ echo $fullGreeting; ?> ``` -### **Node** +### Node To use Node.js, you need to add the path to the node interpreter, which is **_/usr/bin/node_**, in the advanced section of your configuration in your code block. @@ -152,7 +152,7 @@ const fullGreeting = `${greeting} It's now ${currentDateTime}`; console.log(fullGreeting); ``` -## **List of Auto-Detected Language Runtimes** +## List of Auto-Detected Language Runtimes Runme auto-detects runtimes based on the language selection per cell. @@ -245,6 +245,6 @@ Runme auto-detects runtimes based on the language selection per cell. Missing a language? Please [raise an issue](https://github.com/stateful/runme/issues/new). -## **Combining Multiple Languages in Your Notebook** +## Combining Multiple Languages in Your Notebook It's possible to combine multiple languages in a single notebook by using different shebang lines for each script block. For an example of a notebook with multiple languages, see the [Shebang Notebooks example on GitHub](https://github.com/stateful/Shebang-Notebooks/blob/main/shebang-example.md).