Merge pull request #337 from stateful/T-iteration3

T iteration3

Author: edeediong

docs/configuration/cell-level.md

@@ -14,7 +14,7 @@ In this section, we will explain the various features of the cell-level option a
 
 ***Let’s dive in!***
 
-### Different Types of Commands
+### **Different Types of Commands**
 
 Not all commands are equal, and expectations of how execution works can differ! For example, code blocks can be:
 
@@ -25,7 +25,7 @@ Not all commands are equal, and expectations of how execution works can differ!
 
 However, Runme makes running such commands easy. It has sophisticated features that ensure commands and code are executed inside your Markdown file. In this section, we will explore how to run commands and code in one click and some features that make running commands at the cell level easier with Runme.
 
-## How to Run a Cell In One Click
+## **How to Run a Cell In One Click**
 
 To run a cell block in your Markdown file:
 
@@ -38,11 +38,11 @@ This action will run your command and return an executed output.
 
 You can configure how your cell should run using the configuration options. In the next section, we will be explaining how to configure your cell using the different cell-level options in Runme.
 
-## Features of the Cell-Level Options
+## **Features of the Cell-Level Options**
 
 The cell-level option is designed with unique sub-features which makes it efficiently and gives users the flexibility to modify each cell to their preference. Some of these features include:
 
-### 1. Configuration of Cell
+### **Configuration of Cell**
 
 Runme provides two distinct ways you can configure your cell.
 
@@ -87,7 +87,7 @@ Take a look at more [examples](https://github.com/stateful/vscode-runme/tree/mai
 
 </Infobox>
 
-### 2. Specify Language in Blocks
+###  **Specify Language in Blocks**
 
 Runme, just like most Markdown viewers, will work best when a script's language is contained inside fenced code blocks.
 
@@ -117,7 +117,7 @@ While this works well in a lot of cases, the accuracy is not perfect.
 
 </Infobox>
 
-### 3. Handle long-running processes
+###  **Handle long-running processes**
 
 It is common to use file-watcher-enabled compilers/bundlers (e.g., `npm start dev`, `watchexec`, etc.) in the background during development.
 For any cell containing an instance of these commands, tick the background cell setting. This will prevent execution from permanently blocking the notebook UX.
@@ -137,7 +137,7 @@ npm run watch
 
 ![background](../../static/img/configuration-page/background-task.png)
 
-### 4. **Cell's current working directory**
+### **Cell's current working directory**
 
 In most cases, you should set the current working directory at the document level; however, you can also set it per cell.
 
@@ -164,7 +164,7 @@ Please note that if both `cwd` is set for doc-level and cell, they don't overw
 
 </Infobox>
 
-### 5. **Interactive vs non-interactive cells**
+###  **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*.
 
@@ -184,7 +184,7 @@ Please note that the Runme team is currently working on making output in both no
 
 </Infobox>
 
-### 6. **Set environment variables**
+###  **Set environment variables**
 
 If a cell has exported variables, the user will be prompted to set these variables. This can be useful to have a parameterized cell while not needing to manually modify the cell.
 
@@ -223,7 +223,7 @@ export PROJECT_ID=Enter a valid project ID
 cli make-call --project-id $PROJECT_ID describe
 ```
 
-### 7. **Terminal visibility post-execution**
+###  **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`).
 
@@ -236,7 +236,7 @@ A cell's execution terminal is auto-hidden unless it fails. This default behavio
 docker ps | grep runme/demo:latest
 ```
 
-### 8. **Human-friendly output**
+###  **Human-friendly output**
 
 Not all cells’ output is plain text. For example, you can have JSON, text, images, etc, all in your Markdown file.
 
@@ -246,7 +246,7 @@ Using the `mimeType` specifier, you can specify the expected output type. Runm
 
 See in the [reference page](../Reference/mime) for the list of supported MIME types!
 
-### 9. **Terminal Row**
+###  **Terminal Row**
 
 On Runme outputs are saved in lines also known as rows. The number of lines or rows in which an output should be rendered is defined by a setting known as Terminal row.
 Terminal row allows you to set the number of rows with which your output should be displayed under a cell.
@@ -270,7 +270,7 @@ We have provided a list of configuration settings to upgrade your experience usi
 
 - Lastly, set the number of rows you wish your output to be rendered in.
 
-### 10. **Unnamed vs Named cells**
+###  **Unnamed vs Named cells**
 
 On Runme cells are unnamed by default. However, you can name a cell directly in your notebook. This will enable you to easily identify the cell using the provided cell name. On the cell you wish to name, simply click on the “Add Name” button on the cell.
 
@@ -315,7 +315,7 @@ Take a look at more [examples](https://github.com/stateful/vscode-runme/tree/mai
 
 </Infobox>
 
-### 11. **Exclude Cell from Run All**
+###  **Exclude Cell from Run All**
 
 Every VS Code notebook allows users to run all available cells. This can be useful if you define a complete runbook in your Markdown file, allowing developers to click the **Run All** button to get set up and running.
 
@@ -331,7 +331,7 @@ However, sometimes certain cells should be excluded from this workflow. You can
 ```
 
 
-### 12. **Run All Cells by Category**
+###  **Run All Cells by Category**
 
 If you have multiple workflows in a single Markdown file you can categorize them and allow your developers to run all cells by a certain category. To enable that you can add a category as a cell option. A cell can have one or multiple categories that are comma-separated.
 

docs/guide/bashscripting.md

@@ -1,26 +1,29 @@
 # Running Bash Scripts in Runme
 
+Looking to automate your workflow?
 
-As a system administrator, DevOps engineer, or developer, dealing with Bash scripts to automate tasks is a common part of your daily routine. To run Bash scripts conventionally, you need to create a `.sh` file for your scripts and ensure it begins with a shebang line (`#!`) to specify the interpreter.
+Runme makes it easy to run bash scripts directly within your Markdown files. With Runme, you can create, manage, and run scripts to automate repetitive tasks, saving time and effort.
 
-All these processes can be made easier with Runme.  [Runme](https://runme.dev/) provides a convenient way to run scripts, code, and commands directly within Markdown files without having to worry about environment configurations.
+This is not just limited to bash; [Runme](https://runme.dev/) supports scripting in various languages like PowerShell, Python, and more. This flexibility allows you to tailor automated solutions to your specific requirements.
+
+In this guide, we will walk you through running a bash script on Runme.
 
-In this guide, we will walk you through executing Bash scripts on Runme.
 
 ## **Setting Up Your Environment**
 
-To get started with Bash scripts in Runme, you need to first install and configure Runme for VS Code. Follow the steps below to perform this task:
+To get started with Bash scripts in Runme, you are required to first install and configure [Runme on your VS Code](https://docs.runme.dev/installation/installrunme) editor. If you do not have Runme on VS Code installed yet, proceed to the Extension tab of your VS Code and search for “**Runme DevOps Notebook**.”
 
-- Install VS Code on your local machine
-- Proceed to the extension tab of your VS Code dashboard which is on the left and search for Runme.
-- Now click install
+![install runme](../../static/img/guide-page/runme-notebooks.png)
 
-![installation of runme](../../static/img/guide-page/runme-notebook.png)
+You can configure your code editor to make Runme your [default Markdown viewer](https://docs.runme.dev/installation/installrunme#how-to-set-vs-code-as-your-default-markdown-viewer). This means you `.md` will be displayed as a runbook whenever you open a Markdown.
 
 ## **Writing Your First Bash Script in Runme**
 
-Runme integrates easily with Bash scripts via the [Shebang](https://docs.runme.dev/configuration/shebang) feature to execute them directly within Markdown files. The Shebang feature not only makes executing easier but also ensures complex processes are made simpler.
-In this section, we will provide you with a step-by-step guide to creating a simple bash script within a Markdown file and executing it with Runme.
+Runme integrates easily with Bash scripts via the [Shebang](https://docs.runme.dev/configuration/shebang) feature, which allows you to run any script you choose directly from the Markdown file in your preferred programming language.
+
+This section will provide a step-by-step guide to creating a simple bash script within a Markdown file and executing it with Runme.
+
+Let’s get started.
 
 1. Create a new folder and open it with your VS code. In your VS code, create a new README.md file.
 2. Click on the + Code icon
@@ -29,62 +32,66 @@ In this section, we will provide you with a step-by-step guide to creating a sim
 
 3. Enter the script you want to run. For this tutorial, we will be using the simple bash script below.
 
-![scripting-exam](../../static/img/guide-page/scripting-output.png)
+![scripting-outputs](../../static/img/guide-page/scripting-outputs.png)
 
-4. Click on Select Cell Language Mode and search for Shell script.
+4. Click on the programming language at the button of the cell. This will display a list of supported languages. .
 
-![cell language](../../static/img/guide-page/laguagemode.png)
 
-5. Now click on the Run button beside your script to execute it.
+![cell language](../../static/img/guide-page/language-mode.png)
+
+5. Search for Shell script.
+
+6. Now click on the Run button beside your script to execute it.
 
 ![run codeblock](../../static/img/guide-page/executionpromt.png)
 
-You have successfully executed your first bash script with Runme
+After an execution time of 2.3 seconds, you will get a similar output:
+
+![run-code](../../static/img/guide-page/runme-users.png)
+You have successfully executed your first bash script with Runme!🎉
 
-![run-code](../../static/img/guide-page/runme-user.png)
+Runme makes it incredibly easy! Previously, you would have to create a .sh   file to execute bash scripts, but with Runme, you do not need to create a new file from scratch. All you need to do is install the Runme extension in VS Code, and you can save yourself the stress of environment issues, as bash scripts run swiftly in Runme regardless of your machine's environment and operating system.
 
-Now you have seen how Runme makes this easy. Previously, to execute bash scripts, you would have to create a .sh   file, but with Runme, you don’t need to create a new file or any other complex stuff. All you need to do is install the Runme extension in VS Code and save yourself the stress of environment issues as bash scripts run swiftly in Runme regardless of the environment and operating system of your machine.
+Let’s dive into more advanced bash scripting actions.
 
 ## **Advanced Bash Scripting Techniques in Runme**
 
-Bash scripts have several advanced techniques that can also be integrated with Rume for  DevOps engineers and SREs. In this section, we will explore some of the advanced features of bash scripting and how they can be integrated with Runme.
+Bash scripts have several advanced techniques that can be integrated with Rume. In this section, we will explore some of the advanced features of bash scripting and how they can be integrated with Runme.
+
+* **Variable Manipulation**:
+
+    Variable manipulation involves modifying or extracting parts of a variable’s value to suit your needs without changing the original data. This can be done and executed in your Markdown file without external dependencies.
+
+    The image below provides an example of how a user can manipulate variables in bash scripts in Runme and the corresponding output the user will get in the terminal.
+
+
+![example](../../static/img/guide-page/var-maniuplation.png)
 
-Shall we?
+* **Conditional Statements**:
 
-* **Variable Manipulation**
-   Variable manipulation, which involves modifying or extracting parts of a variable’s value to suit your needs without changing the original data, can be done and executed in your Markdown file without any external dependencies. The image below gives an example of how a user can perform variable manipulation of Bash scripts in Runme and the corresponding output the user will get in the terminal.
+  If you have a series of conditional statements in a Bash script that you would love to execute, Runme makes this easy. All you need to do is create a .md file in your editor, enter your script, and click the Run cell button.
 
-![example](../../static/img/guide-page/variable-manipulation.png)
+  The image below shows how a conditional statement in a Bash script is executed in Runme in VS Code.
 
-* **Conditional Statements**
-   Suppose you have a series of conditional statements in a Bash script that you would love to execute, Runme makes this easy for you. All you need to do is create a READMe.md file in VS Code, enter your script, and click the run cell button. The image below is an example of how a conditional statement in Bash script is executed using Runme in VS Code.
 
-![if-statement](../../static/img/guide-page/if-statement.png)
+![if-statement](../../static/img/guide-page/ifstatement.png)
 
-* **Integrating Runme with Docker**
-   You can use Runme to write several bash scripts that execute commands in Docker. For example, the script below manages a Docker container for an Nginx web server.
+* **Integrating Runme with Docker**:
+  You can use Runme to write several bash scripts that execute Docker commands. The script below manages a Docker container for an Nginx web server.
 
-![bash-docker](../../static/img/guide-page/bash-docker.png)
+![bash-docker](../../static/img/guide-page/docker-bash.png)
 
-* **Strategies for leveraging Runme’s features**
-   Efficiency, reliability, and scalability are three paramount keys to thriving in the site reliability engineering and DevOps space.
-   Leveraging Runme's features can provide these three keys and also significantly enhance the management and execution of Bash scripts, thereby simplifying your tasks and workflows. Here's how you can optimize Bash scripts for SRE tasks using Runme's key features:
+### How to optimize Bash scripts using Runme's key features:
 
-1. Archiving for Historical Reference and Audit Trails
-   Runme has an archiving feature that offers a structured approach to storing outputs generated from executed code. With this feature, you can create historical records and audit trails of previous script executions.
-   This feature also comes in handy for troubleshooting and performance analysis purposes. In addition, archived outputs are securely stored in the Runme cloud, which ensures accessibility and data integrity.
-2. Lifecycle Identity for Versioning and Tracking
-   Runme’s lifecycle identity for versioning and tracking allows DevOps engineers and SREs to assign unique identifiers and versions to cells. This facilitates easy version control and tracking of script modifications over time.
+- **Lifecycle Identity for Versioning and Tracking**
 
-   This feature greatly offers ease to users as monitoring of changes, identification of issues, and maintenance of documentation integrity become easier. By adopting lifecycle identity, Bash script execution becomes more manageable and maintainable.
+Runme’s [lifecycle identity](https://docs.runme.dev/configuration/lifecycle-identity) for versioning and tracking enables you to assign unique identifiers and versions to cells. This will ensure easy version control and tracking of the script whenever an update is made.
 
-3. Shebang Support for Seamless Integration and Execution
-   Runme's Shebang support enables the swift integration and execution of Bash scripts within Runme's environment. With this feature, SREs can specify the desired interpreter version and environment configurations directly within the script. This ensures consistency and compatibility across different environments, making Bash scripts more portable and reusable. Additionally, shebang support simplifies the execution process, allowing SREs to focus on the core tasks without worrying about setup or compatibility issues.
-4. Auto-save feature and separate session outputs
-   The auto-save feature provides a uniform approach to task automation by ensuring that the history of the Markdown text and all cell output produced while running your file are preserved without manual intervention from you or your teammates.
+- **Auto-save feature and separate session outputs**
 
+The [auto-save](https://docs.runme.dev/configuration/auto-save) feature provides a uniform approach to task automation by ensuring that the history of the Markdown command and all cell output produced while running your file is stored without manual intervention.
 
-The auto-save feature incorporates a separate session output method that securely saves when each cell was run, the time it took, and exit codes.
+Runme auto-save incorporates a [separate session](https://docs.runme.dev/configuration/auto-save#session-outputs) output method that securely saves the time each cell was run and its exit codes. It stores this output in an external file for easy reference.
 
 <br />
 <Infobox type="sidenote" title="Note">
@@ -93,13 +100,13 @@ When working with this feature, you are not to push the session outputs to git o
 
 </Infobox>
 
-By strategically incorporating these features into Bash scripts, SREs can enhance productivity, reliability, and scalability in managing infrastructure and ensuring service availability. Whether it's troubleshooting incidents, automating routine tasks, or optimizing system performance, Runme empowers SREs to tackle challenges with confidence and efficiency.
+Incorporating these features into your bash scripts simplifies your automation process, reduces scalability in managing infrastructure, and ensures service availability, whether troubleshooting incidents, automating routine tasks, or optimizing system performance.
 
-## **Conclusion**
-Using Runme to execute your Bash scripts makes execution time faster and provides more ease for you. In this tutorial, we considered how you can execute your first bash script in Runme, advanced Bash scripts you can execute in Runme, and lastly, features in Runme that make the execution of tasks as an SRE expert, DevOps engineer, or system administrator easier.
-You can take a look at our [tutorial page](https://docs.runme.dev/guide/) to find out more ways you can use Runme to make your task seamless.
 
+### Conclusion
 
+Using Runme to execute your Bash scripts automates your process, whether it is a development, testing, or deployment task. This enables you to avoid repetitive tasks and environment compatibility issues. In this tutorial, we delved into how you can execute your first Bash script in Runme, advanced Bash scripts you can execute in Runme, and lastly, features in Runme that make the execution of tasks as an SRE expert, DevOps engineer, or system administrator easier.
 
 
+You can easily integrate Runme with your favourite cloud native tools. Take a look at our [tutorial page](https://docs.runme.dev/guide/) to learn more ways to use Runme to make your tasks seamless.