Repository: stateful/vscode-runme
Pull request #873 (2023-10-05 16:30:52)

Improve readme files docs


Patch:
diff --git a/README.md b/README.md
index 9af5fb3e..a869fdea 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # [Runme](http://runme.dev) for [Visual Studio Code](https://code.visualstudio.com/) [![Tests](https://github.com/stateful/vscode-runme/actions/workflows/test.yml/badge.svg)](https://github.com/stateful/vscode-runme/actions/workflows/test.yml)
 
-This VS Code extension transparently opens markdown files (i.e. README.md) as runnable VS Code notebooks (with the click of a `play` button). Annotating markdown code blocks repo maintainers can enhance the interactive runbook-like experience of their markdown notebooks while they will continue to render properly in markdown viewers. Runme is open source and licensed under APL2.0.
+This VS Code extension transparently opens markdown files (i.e. README.md) as runnable VS Code notebooks (with the click of a `play` button). Annotating markdown code blocks repo maintainers can enhance the interactive runbook-like experience of their markdown notebooks while they will continue to render properly in markdown viewers. Runme is [open source](https://docs.runme.dev/open-source) and licensed under APL2.0.
 
 > 💡 If you don't want the runme notebook, you can always right click on the .md file, click `Open With...` and select the text editor. To make your choice permanent pick "Configure default editor for...".
 
@@ -31,7 +31,7 @@ After cloning into a repo in VS Code, open any markdown file and notice that ins
 
 ## Configure Cell Execution
 
-Runme allows code blocks to be annotated with attributes to provide control over some aspects of execution, output, interaction, and other behavior. Please find a complete list in the [docs](https://docs.runme.dev/configuration).
+Runme allows code blocks to be annotated with attributes to provide control over some aspects of execution, output, interaction, and other behavior. Please find a complete list in the [docs](https://docs.runme.dev/configuration#cell-level-options).
 
 For instance, the following annotation will run the command in the background, great for compilers/bundler with file watchers. To enable or disable any of the available options just click the respective cell's `Configure` button.
 
@@ -39,13 +39,29 @@ For instance, the following annotation will run the command in the background, g
     npx tsc --watch
     ```
 
+## Configure Document-level Execution
+RUNME does not just retain frontmatter, it supports top-level settings that will affect all cells in the document.
+
+```
+---
+shell: bash
+# or
+shell: zsh
+# or
+shell: /bin/ksh
+---
+```
+
 Check the complete list of configuration options at https://docs.runme.dev/configuration or take a look at the [examples](https://github.com/stateful/vscode-runme/tree/main/examples) which are also illustrated in [Runme's integration docs](https://docs.runme.dev/integrations).
 
+## Frequently Asked Questions
+Chances are, you're not the first trailblazer to wander through here – someone might have already asked that burning question of yours, and we've got it covered. But hey, you might just be the pioneer with a fresh perspective! So feel free to ask away – your question could be the start of something new, and we're all ears! [Checkout out our official FAQ](https://docs.runme.dev/faq)
+
 ## Maturing Software
 
 Runme is in rapid development. Please be aware of following known limitations:
 
-- Only shell is currently supported on macOS, Linux, and Windows ([WSL](<[url](https://learn.microsoft.com/en-us/windows/wsl/)>)). PowerShell is not supported yet
+- Only shell is currently supported on macOS, Linux, and Windows ([WSL]([url](https://learn.microsoft.com/en-us/windows/wsl/))). PowerShell is not supported yet
 - Be aware of edge cases. Let us know when you hit any snags. We appreciate it!
 
 We would love to hear feedback, appreciate your patience, as Runme continutes to harden. Get in touch please!
@@ -54,3 +70,4 @@ We would love to hear feedback, appreciate your patience, as Runme continutes to
 - [Submit an Issue](https://github.com/stateful/runme/issues)
 - [Contribute on Github](https://github.com/stateful/vscode-runme/blob/main/CONTRIBUTING.md)
 - [Read the Docs](https://docs.runme.dev/)
+- [Join Runme cloud, it's free](https://runme.dev/)
diff --git a/examples/CATEGORIES.md b/examples/CATEGORIES.md
index 7facf292..9dd5c2ee 100644
--- a/examples/CATEGORIES.md
+++ b/examples/CATEGORIES.md
@@ -5,7 +5,7 @@ title: Examples
 
 # Runme Examples
 
-This `CATEGORIES.md` contains some examples for testing this extension.
+This `CATEGORIES.md` contains examples for running automated e2e tests for this extension.
 
 # Extension Example Markdown Files
 
diff --git a/examples/README.md b/examples/README.md
index 3a97901d..992a9e9d 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -5,7 +5,7 @@ title: Examples
 
 # Runme Examples
 
-This `README.md` contains some examples for testing this extension.
+This `README.md` contains examples for running automated e2e tests for this extension.
 
 # Extension Example Markdown Files
 
diff --git a/examples/enhance/README.md b/examples/enhance/README.md
index 64713420..c70b9972 100644
--- a/examples/enhance/README.md
+++ b/examples/enhance/README.md
@@ -1,10 +1,12 @@
 # Enhance
 
-This project is a showcase for deploying apps with Begin and [Runme Extension](https://marketplace.visualstudio.com/items?itemName=stateful.runme).
+This project is a showcase for deploying apps with [Begin](https://begin.com/) and [Runme Extension](https://marketplace.visualstudio.com/items?itemName=stateful.runme).
+Begin is an end-to-end platform for building fullstack web apps that are highly stable, easily maintainable, yet extremely fast and full-featured.
 
 ## Prerequisites
 
 This project is based on the HTML-first [Enhance](https://enhance.dev/) framework run. It requires [Node.js](https://nodejs.org/en/download) to be installed on your machine.
+Enhance is an HTML-first full-stack web framework that gives you everything you need to build standards-based multi-page web apps that perform and scale.
 
 Before you start make sure to install the dependencies of the project:
 
@@ -30,27 +32,27 @@ This will watch the project directory and restart as necessary.
 
 ### Deployment
 
-To deploy this project you need to have `begin` CLI installed on your system. To
+To deploy the `begin` project example you need to have `begin` CLI installed on your system. To
 install, please run:
 
 ```sh { closeTerminalOnSuccess=false interactive=false }
 curl -sS https://dl.begin.com/install.sh | sh
 ```
 
-Ensure you have the CLI installed:
+To check you have `begin` CLI installed, you can run the following command:
 
 ```sh
 begin version
 ```
 
-If not, ensure that the CLI was added your `$PATH`:
+If you have `begin` CLI installed, but still not working, ensure that the CLI was added your `$PATH`:
 
 ```sh
 export BEGIN_INSTALL="$HOME/.begin"
 export PATH="$BEGIN_INSTALL:$PATH"
 ```
 
-Once installed successfully, you can log into your Begin account via:
+To get started with Begin, once you have `begin` CLI installed and configured, you can log into your Begin account via:
 
 ```sh
 begin login
diff --git a/examples/fresh/README.md b/examples/fresh/README.md
index 7421d35c..172fa413 100644
--- a/examples/fresh/README.md
+++ b/examples/fresh/README.md
@@ -7,8 +7,7 @@ This project is a showcase for deploying apps with Deno and [Runme Extension](ht
 This project is based on [Fresh](https://fresh.deno.dev/) and requires Deno to
 run.
 
-To test if you already have Deno installed run:
-If this prints the Deno version to the console the installation was successful.
+You can test if you already have deno installed by running the following command:
 
 ```sh { closeTerminalOnSuccess=false interactive=false }
 deno --version
@@ -34,7 +33,7 @@ Or the installer which also works on Linux:
 curl -fsSL https://deno.land/x/install/install.sh | sh
 ```
 
-Add Deno to your path:
+Once Deno is installed, ensure is added to your path:
 
 ```sh
 export DENO_INSTALL="$HOME/.deno"
@@ -59,7 +58,9 @@ This will watch the project directory and restart as necessary.
 
 ### Deployment
 
-To deploy this project you need to have `deployctl` installed on your system. To
+We will be using [Deno deploy](https://deno.com/deploy) a serverless edge first JavaScript hosting service.
+
+To deploy this project you need to have `deployctl` (the command line tool for Deno Deploy) installed on your system. To
 install, please run:
 
 ```sh { closeTerminalOnSuccess=false interactive=false }
diff --git a/examples/k8s/README.md b/examples/k8s/README.md
index 0bd958d7..b7f90afb 100644
--- a/examples/k8s/README.md
+++ b/examples/k8s/README.md
@@ -1,4 +1,6 @@
 # Deploying a Dockerized React App to Kubernetes Cluster
+Learn how to dockerize a React App and deploy it to a Kubernetes cluster with Linkerd.
+Using the Linkerd CLI, you’ll install the control plane onto your Kubernetes cluster. Finally, you’ll “mesh” a application by adding Linkerd’s data plane to it.
 
 ## Prerequisites
 
diff --git a/examples/shebang.md b/examples/shebang.md
index e682bd70..e3de46a0 100644
--- a/examples/shebang.md
+++ b/examples/shebang.md
@@ -1,6 +1,7 @@
 # Runme Language Support
 
 By default Runme can run everything that is also installed on your machine.
+Read more in our [docs](https://docs.runme.dev/features#interpreter)
 
 ## Like Python:
 
diff --git a/examples/vercel/README.md b/examples/vercel/README.md
index 4f628e3a..20c7bb01 100644
--- a/examples/vercel/README.md
+++ b/examples/vercel/README.md
@@ -1,6 +1,7 @@
 # Deploy Next.js with Runme
 
 This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
+Next.js enables you to create full-stack Web applications by extending the latest React features, and integrating powerful Rust-based JavaScript tooling for the fastest builds
 
 ## Getting Started
 
@@ -26,6 +27,10 @@ You can start editing the page by modifying `pages/index.tsx`. The page auto-upd
 
 [API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.ts`.
 
+```sh
+open http://localhost:3000/api/hello
+```
+
 The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages.
 
 ## Learn More


Test patch:
diff --git a/examples/test.md b/examples/test.md
index fff8c59c..7a6fe247 100644
--- a/examples/test.md
+++ b/examples/test.md
@@ -1,6 +1,7 @@
 # Runme Examples
 
-This `README.md` contains some examples for testing this extension.
+This `README.md` contains some examples for executing e2e tests for the extension.
+It covers Cell shell executions, GitHub integration and Codelense test suites
 
 # Extension Example Markdown Files