Merge pull request #476 from stateful/admc/simplifying

More docs simplification and formatting

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

docs/configuration/output-rendering.md

@@ -1,31 +1,25 @@
----
-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.
 
 ![Runme mimetype](/img/guide-page/runme-mimetype.png)
 
 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:
   <source src="/videos/runme-data-rendering.webm" type="video/webm" />
 </video>
 
-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.
+<br />
+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:

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,15 +57,15 @@ 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:
 
 ```bash {"id":"01J58R4TJ430708WYDMTRV0677"}
 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

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 <command>` 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 <command>` to execute tasks defined in the Markdown `.md` files.
 
 ![runme cli](/img/how-runme-works/runme-cli-windows.png)