feat: reorganized content, better readme

Author: simonmeggle

.github/scripts/sync-examples.sh

@@ -55,9 +55,22 @@ build_header() {
   local repo_id="$2"
   local has_devcontainer="$3"
   local badge
-  badge="$(build_codespaces_badge "${repo_id}" "${has_devcontainer}")"
+  # no button at the beginning
+  #badge="$(build_codespaces_badge "${repo_id}" "${has_devcontainer}")"
   [[ -n "${badge}" ]] && printf '%s\n\n' "${badge}"
+
+# <picture>
+#   <source media="(prefers-color-scheme: dark)" srcset="https://www.robotmk.org/rmk_crop_transp_w150.png">
+#   <source media="(prefers-color-scheme: light)" srcset="https://www.robotmk.org/rmk_crop_transp_150.png">
+# </picture>
+}
+
+build_footer() {
+
+
   cat <<EOF
+> ---
+>
 > **This repository is automatically synced from [${SOURCE_REPO}](https://github.com/${SOURCE_REPO}/tree/main/examples/${name}).**
 > Do not edit files here directly — changes will be overwritten on the next sync.
 > Last sync: [\`${SOURCE_SHA:0:7}\`](https://github.com/${SOURCE_REPO}/commit/${SOURCE_SHA})
@@ -66,20 +79,6 @@ build_header() {
 
 EOF
 
-# <picture>
-#   <source media="(prefers-color-scheme: dark)" srcset="https://www.robotmk.org/rmk_crop_transp_w150.png">
-#   <source media="(prefers-color-scheme: light)" srcset="https://www.robotmk.org/rmk_crop_transp_150.png">
-# </picture>
-}
-
-build_footer() {
-  local repo_id="$1"
-  local has_devcontainer="$2"
-  local badge
-  badge="$(build_codespaces_badge "${repo_id}" "${has_devcontainer}")"
-  if [[ -n "${badge}" ]]; then
-    printf '\n%s\n' "${badge}"
-  fi
 }
 
 prepend_header() {

.github/scripts/update_suite_table.py

@@ -92,25 +92,21 @@ def get_space(suite_dir: Path) -> str:
 
 def build_table(repo_root: Path, parent: str) -> str:
     is_examples = parent == "examples"
-    header = "| Suite | Description | Dependencies |" + (" Repo |" if is_examples else "")
-    sep    = "|---|---|---|" + ("---|" if is_examples else "")
+    header = "| Robot Framework Suite | Description |" + (" Repository Link |" if is_examples else "")
+    sep    = "|---|---|" + ("---|" if is_examples else "")
     rows = []
     parent_dir = repo_root / parent
     if parent_dir.exists():
         for suite_dir in sorted(parent_dir.iterdir()):
             if not suite_dir.is_dir() or suite_dir.name.startswith("."):
                 continue
             name = suite_dir.name
-            v = parse_conda_versions(suite_dir / "conda.yaml")
             doc = parse_suite_doc(suite_dir)
             rel = f"{parent}/{name}"
-            deps = "<br>".join(
-                f"• {pkg}=={version}" for pkg, version in sorted(v.items())
-            )
             repo_col = ""
             if is_examples:
                 repo_col = f" [try out](https://github.com/robotmk/example-{name}) |"
-            rows.append(f"| [{name}]({rel}) | {doc} | {deps} |{repo_col}")
+            rows.append(f"| [{name}]({rel}) | {doc} |{repo_col}")
     return "\n".join([header, sep] + rows)
 
 

README.md

@@ -4,36 +4,38 @@
   <img alt="Robotmk" src="https://www.robotmk.org/rmk_crop_transp_150.png">
 </picture>
 
-# robotmk-starter
-
 <!-- CI-BADGE-START -->
 [![Run Suites](https://github.com/elabit/robotmk-starter/actions/workflows/run-suites.yml/badge.svg)](https://github.com/elabit/robotmk-starter/actions/workflows/run-suites.yml)
 <!-- CI-BADGE-END -->
+# robotmk-starter
+
+
 
-![alt text](docs/img/cmk_rmk_small.png)
+## What is this?
 
-> **Ready-to-run Robot Framework suites for [Checkmk](https://checkmk.com) synthetic monitoring with [Robotmk](https://www.robotmk.org), the [Robot Framework](https://robotframework.org/) integration for Checkmk.**
+This repository provides **working examples** to learn and test [Robot Framework](https://robotframework.org/) automation - the test scripting language used by [Robotmk](https://www.robotmk.org) for *Synthetic Monitoring* in [Checkmk](https://checkmk.com).
 
-This repo gives you a running starting point.
+## Choose your path:
 
-## Overview
+You want to...
 
-Two kinds of content live here:
+- ... play around with working **Robot Framework** examples?  
+  → Read the [example guide](docs/example_guide.md) - *Copy/Paste the examples or try them online.*
+- ... need a skeleton to start your own **Robot Framework** suite?  
+  → Check out the [templates](templates/) folder - *Copy one, fill in your test steps, run it.*
+- ... 🚀 want to **start a Checkmk playground** to live test **Robotmk** for Synthetic Monitoring*?  
+  → Read the [Checkmk codespace documentation](docs/CMK-Codespace.md).  
 
-|                  | [`examples/`](examples/)         | [`templates/`](templates/)              |
-|------------------|----------------------------------|-----------------------------------------|
-| **What**         | Full working RF suites              | Minimal skeletons                       |
-| **Purpose**      | Learn by example, adapt and copy | Blank canvas for your own suite         |
 
-The tables below are auto-generated from each suite's content and refreshed on every CI run.
 
 
-## /examples
+## Content
 
-All examples are automatically deployed to individual GitHub repositories.  
-Click on "*try out*" to open the example repo, where you find instructions to run it locally, in VS Code, or online in the Github Codespace.
+### Folder "/examples"
 
+A great starting point to **learn** from working Robot Framework test suites. 
 
+To try them out, just click on "*try out*" which opens the repository, where you find instructions.
 
 <!-- EXAMPLES-TABLE-START -->
 
@@ -45,25 +47,13 @@ Click on "*try out*" to open the example repo, where you find instructions to ru
 
 <!-- EXAMPLES-TABLE-END -->
 
-### Your Checkmk Playground: Codespace
-
-As a **bonus**, this repo also contains a Checkmk `.devcontainer/` that spins up a full **CheckMK Pro** instance with a **Fluxbox/noVNC desktop**.  
-
-![alt text](docs/img/cmk_disc_small.png)
-
-This is useful to play around with **Checkmk**, **Robotmk** and all the examples together in a pre-configured environment **without installing anything locally**.  
-
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=1229554077)
-
-Also read the [Full Guide: How to use Checkmk in Codespace](docs/CMK-Codespace.md)
-
-
 ---
 
-## /templates
+### Folder "/templates"
+
+These templates provide useful **skeletons** when you want to start your own Robot Framework suite.  
 
-Templates are minimal — they contain the structure/concept but not the logic.
-Copy one, fill in your test steps, run it.
+Each template focuses on a specific use case or integration, providing a ready-to-use structure and example test cases.
 
 <!-- TEMPLATES-TABLE-START -->
 
@@ -78,30 +68,17 @@ Copy one, fill in your test steps, run it.
 ## For maintainers
 
 Examples and templates are generated from Copier sources in `_dev/`.
-Version pins live in a single file — one edit, one `task generate`, done.
-
-→ [_dev/README.md](_dev/README.md)
-
-
-## Closing Notes
-
-This is only the beginning of the journey, there is a lot more to explore in the world of **Robot Framework, Robotmk and Checkmk**.  
+Version pins live in a single file with packages and versions — edit, `task generate`, done.
 
-In case you have found a bug or have suggestions for improvements, please feel free to open an issue or even better, a pull request.
+→ [Dev documentation](_dev/README.md)
 
-If you want to learn more, there are several ways of how we can support you:
 
-- [Synthetic Monitoring Trainings](https://lp.robotmk.org/robotmk-masterclass-4d-en)
-- Implementing a **Robotmk POC** in your company
-- Know How Transfer
-- Code Review of existing Tests & Coaching Sessions
-- "Extended Workbench" - We work together on your test automation projects for a defined period of time
+## About
 
-Reach out to us via mail at robotmk.org or book a free [clarification call](https://meet.brevo.com/simon-meggle).
+Found a bug or have a suggestion?  
+→ [Open an issue](https://github.com/robotmk/robotmk-starter/issues) or submit a [pull request](https://github.com/robotmk/robotmk-starter/pulls) — contributions are welcome.
 
-![alt text](docs/img/portrait_simon_meggle_rund_feiner_rahmen_KLEIN.png)
+Want to go deeper? Want ot get a certified professional?  
+→ I offer [Synthetic Monitoring Trainings](https://lp.robotmk.org/robotmk-masterclass-4d-en) or book a free [call](https://meet.brevo.com/simon-meggle).
 
-**Simon Meggle**  
-*CEO Elabit GmbH*  
-*Founder of Robotmk*  
-*Product Manager of Synthetic Monitoring at Checkmk*
+**Simon Meggle** — Founder of Robotmk, Product Manager Synthetic Monitoring at Checkmk

_dev/_examples/cryptolibrary-simple/README.partial.md

@@ -1,9 +1,12 @@
 # cryptolibrary-simple
 
-Minimal example for using [robotframework-crypto](https://github.com/Snooz82/robotframework-crypto) with Robotmk.
-Demonstrates how to store an encrypted secret in a Robot Framework suite and decrypt it at runtime using a private key file — no plaintext passwords anywhere in the codebase.
+{% include 'how-to-run.partial.md' %}
+
+## About this Robot Framework test
+
+Minimal example for using [robotframework-crypto](https://github.com/Snooz82/robotframework-crypto) with Robotmk.  
+Demonstrates how to store an encrypted secret in a Robot Framework suite and decrypt it at runtime using a private key file — no plaintext passwords anywhere in the codebase!
 
-## What This Demonstrates
 
 - Encrypting a password with `CryptoLibrary` and storing the `crypt:…` value in the suite
 - Passing the key password via an environment variable (`RMKCRYPTPW`)
@@ -15,18 +18,15 @@ Demonstrates how to store an encrypted secret in a Robot Framework suite and dec
 |---|---|
 | `Test Password Equality` | Decrypts an encrypted password string and asserts it equals the known plaintext |
 
-## Key Files
-
-| File | Purpose |
-|---|---|
-| `suite.robot` | Single test suite with the `Test Password Equality` test case |
-| `conda.yaml` | Python environment (Python `{{ python_version }}`, robotframework-crypto `{{ rf_lib_crypto_version }}`) |
-| `robot.toml` | Sets the `RMKCRYPTPW` environment variable consumed by CryptoLibrary |
-| `keys/private_key.json` | Demo private key for decryption — replace with your own in production |
-| `.devcontainer/devcontainer.json` | VS Code devcontainer with RCC pre-installed |
 
 ## Links
 
+### Recommended links for this example
+
+- [Robotmk Blog: How to use the CryptoLibrary](https://www.robotmk.org/en/blog/cryptolibrary/)
+
+### General links & Documentation
+
 - [robotframework-crypto](https://github.com/Snooz82/robotframework-crypto)
 - [Robot Framework](https://robotframework.org)
 - [Robotmk Homepage](https://robotmk.org)

_dev/_examples/cryptolibrary-simple/template/suite.robot

@@ -1,5 +1,5 @@
 *** Settings ***
-Documentation       TODO
+Documentation       A minimalistic example of how to use the **CryptoLibrary**, without bells and whistles.
 
 Library     CryptoLibrary
 ...             key_path=${CURDIR}/keys
@@ -12,6 +12,6 @@ ${PASSWORD_CRYPT}   crypt:CorBEZOtizedq5WviZc7nTGiIPle6Bwd5r222Er0sUIS/7jTrkTkxm
 
 *** Test Cases ***
 Test Password Equality
-    [Documentation]    TODO
+    [Documentation]    Tests whether the decrypted text matches the expected value.
     ${pass}   Get Decrypted Text  ${PASSWORD_CRYPT}
     Should Be Equal As Strings  ${pass}  password123456

_dev/_examples/rf-custom-library/README.partial.md

@@ -1,9 +1,12 @@
 # rf-custom-library
 
+{% include 'how-to-run.partial.md' %}
+
+## About this Robot Framework test
+
 Minimal example for extending Robot Framework with a custom Python library.
 Demonstrates how to write a simple Python class, expose its methods as keywords via the `@keyword` decorator, and import the library directly into a suite.
 
-## What This Demonstrates
 
 - Writing a custom Robot Framework library as a plain Python class (`CustomLibrary.py`)
 - Exposing Python methods as RF keywords with `@keyword` from `robot.api.deco`
@@ -17,17 +20,13 @@ Demonstrates how to write a simple Python class, expose its methods as keywords
 | `Test Hello` | Calls the `Say Hello` keyword and logs a greeting |
 | `Test Addition` | Calls `Add Numbers` with two integers and logs the result |
 
-## Key Files
-
-| File | Purpose |
-|---|---|
-| `suite.robot` | Suite importing `CustomLibrary.py` with two test cases |
-| `CustomLibrary.py` | Custom library with `Say Hello` and `Add Numbers` keywords |
-| `conda.yaml` | Python environment (Python `{{ python_version }}`, robotframework `{{ rf_version }}`) |
-| `robot.yaml` | RCC task and environment configuration |
 
 ## Links
 
+### Recommended links for this example
 - [Robot Framework — Extending with Python](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#creating-test-libraries)
+
+### General links & Documentation
+
 - [Robot Framework](https://robotframework.org)
 - [Robotmk Homepage](https://robotmk.org)

_dev/_examples/rf-custom-library/template/suite.robot

@@ -1,12 +1,14 @@
 *** Settings ***
-Documentation  This suite demonstrates the use of a custom library, written with a simple Python class.
+Documentation  This suite demonstrates the use of a **custom library**, written with a simple Python class.
 Library  CustomLibrary.py
 
 *** Test Cases ***
 
 Test Hello 
+    [Documentation]  Calls the user keyword "Say Hello"
     Say Hello  Robots
 
 Test Addition
+    [Documentation]  Calls the user keyword "Add Numbers" to do a calculation
     ${result}=  Add Numbers  44  11
     Log  ${result}

_dev/_examples/rf-python-varfiles/README.partial.md

@@ -1,9 +1,12 @@
 # rf-python-varfiles
 
+{% include 'how-to-run.partial.md' %}
+
+## About this Robot Framework test
+
 Minimal example for loading variables and configuration into a Robot Framework suite from Python and YAML files.
 Demonstrates the three variable file patterns supported by RF: plain scalars, nested dicts, and the `get_variables()` function — plus YAML as a data-format alternative to Python.
 
-## What This Demonstrates
 
 - Exposing computed scalar values (e.g. current user, timestamp) from a Python variable file
 - Accessing values from a nested dict loaded via a Python variable file using the `[key]` subscript syntax
@@ -20,20 +23,13 @@ Demonstrates the three variable file patterns supported by RF: plain scalars, ne
 | `Test YML-Nested` | How to load a nested data structure from a YAML variable file |
 | `Test Get-Variables With Argument` | How to use `get_variables()` to return different variable sets based on an argument passed at import time |
 
-## Key Files
-
-| File | Purpose |
-|---|---|
-| `suite.robot` | Suite importing all four variable files and demonstrating each pattern |
-| `Data/pyvars-simple.py` | Plain variable file with computed scalars (user, timestamp, random int) |
-| `Data/pyvars-nested.py` | Nested environment config dict (`dev` / `test` / `prod`) |
-| `Data/ymlvars-nested.yaml` | Same environment config structure as a YAML variable file |
-| `Data/pyvars-getvariables.py` | `get_variables(browser)` returning browser-specific config profiles |
-| `conda.yaml` | Python environment (Python `{{ python_version }}`, robotframework `{{ rf_version }}`) |
-| `robot.yaml` | RCC task and environment configuration |
 
 ## Links
 
+### Recommended links for this example
 - [Robot Framework — Variable Files](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#variable-files)
+
+### General links & Documentation
+
 - [Robot Framework](https://robotframework.org)
 - [Robotmk Homepage](https://robotmk.org)

_dev/_examples/rf-python-varfiles/template/suite.robot

@@ -1,5 +1,5 @@
 *** Settings ***
-Documentation    This suite demonstrates how to load variables from Python and YAML variable files.
+Documentation    A suite to demonstrate how to load **variables** from **Python**, **JSON** and **YAML** variable files, including nested data structures.
 Variables        Data/pyvars-simple.py
 Variables        Data/pyvars-nested.py
 Variables        Data/pyvars-getvariables.py  ${BROWSER}

_dev/_examples/web-cryptolibrary/README.partial.md

@@ -1,11 +1,14 @@
 # web-cryptolibrary
 
+{% include 'how-to-run.partial.md' %}
+
+## About this Robot Framework test
+
 Example combining [robotframework-browser](https://robotframework-browser.org) (Playwright) with
 [robotframework-crypto](https://github.com/Snooz82/robotframework-crypto).
 Shows how to safely inject an encrypted password into a web login form without ever
 exposing the plaintext in suite files.
 
-## What This Demonstrates
 
 - Browser-based login using Playwright (`rfbrowser`) together with CryptoLibrary
 - The difference between a clear-text password (negative example) and an encrypted password (recommended)
@@ -19,19 +22,16 @@ exposing the plaintext in suite files.
 | `Login With Clear Text Password` | **Negative example** — logs in with a hardcoded plaintext password. Never do this in production. |
 | `Login With CryptoLibrary` | **Recommended** — decrypts the stored `crypt:…` password at runtime and uses `Fill Secret` |
 
-## Key Files
-
-| File | Purpose |
-|---|---|
-| `suite.robot` | Two test cases on [practicetestautomation.com](https://practicetestautomation.com/practice-test-login/) |
-| `conda.yaml` | Environment (Python `{{ python_version }}`, Browser `{{ rf_lib_browser_version }}`, Crypto `{{ rf_lib_crypto_version }}`) |
-| `robot.toml` | Sets `RMKCRYPTPW` (key password) and `ROBOTMK_HEADLESS_HOST` |
-| `keys/private_key.json` | Demo private key for credential decryption |
-| `.devcontainer/devcontainer.json` | Devcontainer with noVNC desktop (port 6080) for headed browser testing |
 
 ## Links
 
-- [robotframework-browser](https://robotframework-browser.org)
+### Recommended links for this example
+
+- [Robotmk Blog: How to use the CryptoLibrary](https://www.robotmk.org/en/blog/cryptolibrary/)
+
+### General links & Documentation
+
 - [robotframework-crypto](https://github.com/Snooz82/robotframework-crypto)
+- [robotframework-browser](https://robotframework-browser.org)
 - [Practice Test Automation – Login page](https://practicetestautomation.com/practice-test-login/)
 - [Robotmk Homepage](https://robotmk.org)