added linter for code block line length and gen_numbering (#70)

## Improvements:

- Code Blocks shall only have a max line length of 100 characters,
because otherwise they are not completely included in the syllabus pdf.
This is now automatically checked during build and build will fail if a
line is longer.
- The Python script to generate the chapter numbers to the headings, has
been improved, to return with an exit code != 0 in case of a fix. This
will now be used as check in the build and also available as pre-commit
hook to the maintainers.

---------

Signed-off-by: René <snooz@posteo.de>

Author: Snooz82

.gitignore

@@ -6,3 +6,4 @@ results
 .vscode
 .devcontainer
 .venv
+Syllabus.pdf

.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: local
+    hooks:
+      - id: gen-numbering
+        name: Ensure numbering, TOC, and links are in sync
+        entry: python tools/gen_numbering.py
+        language: system
+        pass_filenames: false
+        always_run: true

CONTRIBUTION.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Thanks for helping us improve the RFCP syllabus! The notes below explain how to bootstrap the tooling, run Docusaurus locally, and keep the docs consistent.
+
+## 1. Install prerequisites
+- Node.js 20+ (needed for Docusaurus and Playwright)
+- Python 3.11+ (the repo bootstrap script creates a virtual environment for you)
+- npm (ships with Node)
+
+## 2. Project setup
+1. From the repository root, bootstrap both the Python and JavaScript toolchains:
+   ```bash
+   python bootstrap.py
+   ```
+   The script upgrades `pip`, installs `pre-commit`, and asks whether you want to pull in the optional PDF toolchain (Robot Framework + Browser batteries from `requirements.txt`, plus Chromium via `rfbrowser install chromium`). Answer "y" only if you plan to regenerate the PDF. Regardless of that choice, the script installs the pre-commit hook and then runs `npm install` inside `website/` so Docusaurus has its dependencies.
+2. Start Docusaurus in development mode while you edit:
+   ```bash
+   cd website  # if not already there
+   npm run start
+   ```
+
+## 3. Quality checks before committing
+- `pre-commit` automatically runs `python tools/gen_numbering.py` on every commit. If headings, learning-objective numbering, or internal links change the hook updates the files, prints a diff, and blocks the commit until you stage the fixes.
+- All fenced code blocks must stay within 100 characters per line. Run `npm run build` in the `website/` directory to check code block line lengths (or let CI run it).
+- Docusaurus validates internal links during builds. Run `npm run build` before submitting a PR to catch broken anchors or missing pages early.
+
+## 4. Generating the syllabus PDF
+To rebuild the syllabus PDF from the Robot Framework assets, run the Robot Framework suite from the repo root:
+
+1. Activate the created virtual environment so local commands use the same interpreters as the hooks:
+   - macOS/Linux: `source .venv/bin/activate`
+   - Windows (PowerShell): `.venv\Scripts\Activate.ps1`
+
+2. Run the suite to generate the PDF:
+    ```bash
+    robot -d results tools/gen_pdf.robot
+    ```
+The PDF and execution logs land inside `results/`.
+
+Following the steps above keeps your local environment consistent with CI and ensures contributions land cleanly. Happy writing!

LOs.csv

@@ -46,16 +46,16 @@
   - LO-2.1.1 (K1) Recall the conditions and requirements for a file to be considered a Suite file
 - [`2.1.2 Sections and Their Artifacts`](website/docs/chapter-02/01_suitefile.md#212-sections-and-their-artifacts)
   - LO-2.1.2 (K1) Recall the available sections in a suite file and their purpose.
-  - [`2.1.2.1 Introduction in `*** Settings ***` Section`](website/docs/chapter-02/01_suitefile.md#2121-introduction-to--settings--section)
+  - [`2.1.2.1 Introduction to `*** Settings ***` Section`](website/docs/chapter-02/01_suitefile.md#2121-introduction-to--settings--section)
     - LO-2.1.2.1-1 (K1) Recall the available settings in a suite file.
     - LO-2.1.2.1-2 (K2) Understand the concepts of suite settings and how to define them.
-  - [`2.1.2.2 Introduction in `*** Variables ***` Section`](website/docs/chapter-02/01_suitefile.md#2122-introduction-to--variables--section)
+  - [`2.1.2.2 Introduction to `*** Variables ***` Section`](website/docs/chapter-02/01_suitefile.md#2122-introduction-to--variables--section)
     - LO-2.1.2.2 (K1) Recall the purpose of the `*** Variables ***` section.
-  - [`2.1.2.3 Introduction in `*** Test Cases ***` or `*** Tasks ***` Section`](website/docs/chapter-02/01_suitefile.md#2123-introduction-to--test-cases--or--tasks--section)
+  - [`2.1.2.3 Introduction to `*** Test Cases ***` or `*** Tasks ***` Section`](website/docs/chapter-02/01_suitefile.md#2123-introduction-to--test-cases--or--tasks--section)
     - LO-2.1.2.3 (K2) Understand the purpose of the `*** Test Cases ***` or `*** Tasks ***` section.
-  - [`2.1.2.4 Introduction in `*** Keywords ***` Section`](website/docs/chapter-02/01_suitefile.md#2124-introduction-to--keywords--section)
+  - [`2.1.2.4 Introduction to `*** Keywords ***` Section`](website/docs/chapter-02/01_suitefile.md#2124-introduction-to--keywords--section)
     - LO-2.1.2.4 (K2) Understand the purpose and limitations of the `*** Keywords ***` section.
-  - [`2.1.2.5 Introduction in `*** Comments ***` Section`](website/docs/chapter-02/01_suitefile.md#2125-introduction-to--comments--section)
+  - [`2.1.2.5 Introduction to `*** Comments ***` Section`](website/docs/chapter-02/01_suitefile.md#2125-introduction-to--comments--section)
 - [`2.2 Basic Suite File Syntax`](website/docs/chapter-02/02_suitefile_syntax.md)
 - LO-2.2 (K2) Understand the basic syntax of test cases and tasks.
 - [`2.2.1 Separation and Indentation`](website/docs/chapter-02/02_suitefile_syntax.md#221-separation-and-indentation)
@@ -222,7 +222,7 @@
 - [`4.2.3 Keyword Teardown`](website/docs/chapter-04/02_teardowns.md#423-keyword-teardown)
   - LO-4.2.3 (K1) Recall key characteristics, benefits, and syntax of Keyword Teardown
 - [`4.3 Initialization Files`](website/docs/chapter-04/03_init_files.md)
-- LO-4.3 (K1) Recall how to define an Initialization Files and its purpose
+- LO-4.3 (K1) Recall how to define Initialization Files and its purpose
 - [`4.3.1 Purpose of Initialization Files`](website/docs/chapter-04/03_init_files.md#431-purpose-of-initialization-files)
 - [`4.3.2 Suite Setup and Suite Teardown of Initialization Files`](website/docs/chapter-04/03_init_files.md#432-suite-setup-and-suite-teardown-of-initialization-files)
   - LO-4.3.2 (K2) Understand the execution order of Suite Setup and Suite Teardown in Initialization Files and their sub-suites and tests|tasks
@@ -282,7 +282,7 @@
 - [`5.2.1 IF Statements`](website/docs/chapter-05/02_control_structures.md#521-if-statements)
   - LO-5.2.1 (K2) Understand the purpose and basic concept of IF-Statements
   - [`5.2.1.1 Basic IF Syntax`](website/docs/chapter-05/02_control_structures.md#5211-basic-if-syntax)
-- [`5.2.2 IF/ELSE IF/ELSE Structure`](website/docs/chapter-05/02_control_structures.md#522-ifelse-ifelse-structure)
+- [`5.2.2 IF/ELSE Structure`](website/docs/chapter-05/02_control_structures.md#522-ifelse-structure)
 - [`5.2.3 Inline IF Statement`](website/docs/chapter-05/02_control_structures.md#523-inline-if-statement)
 - [`5.2.4 FOR Loops`](website/docs/chapter-05/02_control_structures.md#524-for-loops)
   - LO-5.2.4 (K2) Understand the purpose and basic concept of FOR Loops

README.md

@@ -0,0 +1,86 @@
+import platform
+import subprocess
+from pathlib import Path
+from venv import EnvBuilder
+
+
+class Colors:
+    """ANSI color codes"""
+
+    BLACK = "\033[0;30m"
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    BROWN = "\033[0;33m"
+    BLUE = "\033[0;34m"
+    PURPLE = "\033[0;35m"
+    CYAN = "\033[0;36m"
+    LIGHT_GRAY = "\033[0;37m"
+    DARK_GRAY = "\033[1;30m"
+    LIGHT_RED = "\033[1;31m"
+    LIGHT_GREEN = "\033[1;32m"
+    YELLOW = "\033[1;33m"
+    LIGHT_BLUE = "\033[1;34m"
+    LIGHT_PURPLE = "\033[1;35m"
+    LIGHT_CYAN = "\033[1;36m"
+    LIGHT_WHITE = "\033[1;37m"
+    BOLD = "\033[1m"
+    FAINT = "\033[2m"
+    ITALIC = "\033[3m"
+    UNDERLINE = "\033[4m"
+    BLINK = "\033[5m"
+    NEGATIVE = "\033[7m"
+    CROSSED = "\033[9m"
+    END = "\033[0m"
+    # cancel SGR codes if we don't write to a terminal
+    if not __import__("sys").stdout.isatty():
+        for attr in dir():
+            if not attr.startswith("_"):
+                if isinstance(getattr(__class__, attr), str):
+                    setattr(__class__, attr, "")
+    elif __import__("platform").system() == "Windows":
+        kernel32 = __import__("ctypes").windll.kernel32
+        kernel32.SetConsoleMode(kernel32.GetStdHandle(-11), 7)
+        del kernel32
+
+
+venv_dir = Path() / ".venv"
+requirements_file = Path("requirements.txt")
+website_dir = Path("website")
+if not platform.platform().startswith("Windows"):
+    venv_bin = venv_dir / "bin"
+    venv_python = venv_bin / "python"
+    venv_pre_commit = venv_bin / "pre-commit"
+else:
+    venv_bin = venv_dir / "Scripts"
+    venv_python = venv_bin / "python.exe"
+    venv_pre_commit = venv_bin / "pre-commit.exe"
+
+if not venv_dir.exists():
+    print(f"Creating virtualenv in {venv_dir}")
+    EnvBuilder(with_pip=True).create(venv_dir)
+
+subprocess.run([venv_python, "-m", "pip", "install", "-U", "pip"], check=True)
+subprocess.run([venv_python, "-m", "pip", "install", "-U", "pre-commit"], check=True)
+install_pdf_tooling = False
+if requirements_file.exists():
+    answer = input(f"{Colors.GREEN}Install Robot Framework + browser batteries for PDF generation?{Colors.END} {Colors.YELLOW}[y/N]: {Colors.END}").strip().lower()
+    install_pdf_tooling = answer in {"y", "yes"}
+    if install_pdf_tooling:
+        subprocess.run([venv_python, "-m", "pip", "install", "-r", str(requirements_file)], check=True)
+        subprocess.run([venv_python, "-m", "Browser.entry", "install", "chromium", "--with-deps"], check=True)
+
+subprocess.run([venv_pre_commit, "install"], check=True)
+
+if website_dir.exists():
+    npm_cmd = ["npm", "install"]
+    print(f"Running {' '.join(npm_cmd)} in {website_dir}")
+    subprocess.run(npm_cmd, cwd=website_dir, check=True)
+
+activate_script = (
+    "source .venv/bin/activate"
+    if not platform.platform().startswith("Windows")
+    else ".venv\\Scripts\\activate"
+)
+
+print(f"\n\nVirtualenv '{Colors.GREEN}{venv_dir}{Colors.END}' is ready and up-to-date.")
+print(f"Run '{Colors.GREEN}{activate_script}{Colors.END}' to activate the virtualenv.")

Syllabus.pdf

@@ -0,0 +1,2 @@
+robotframework-browser-batteries
+pypdf

bootstrap.py

@@ -0,0 +1 @@
+

requirements.txt

@@ -5,6 +5,8 @@ Library     Process
 
 *** Variables ***
 @{EXCLUDE_FROM_PDF}    Example Questions
+${BROWSER}    chromium
+${HEADLESS}    ${True}
 
 
 *** Test Cases ***
@@ -22,7 +24,11 @@ Build Docusaurus
     Process.Start Process    npm    run    serve    alias=docusaurus    cwd=website
 
 Open Syllabus
-    New Browser    chromium    headless=False
+    IF   $BROWSER.lower() in ['chrome', 'msedge']
+        New Browser    chromium    channel=${BROWSER}    headless=${HEADLESS}
+    ELSE
+        New Browser    chromium    headless=${HEADLESS}
+    END
     New Page    http://localhost:3000/robotframework-RFCP-syllabus/docs/overview
     ${dark}    Get Element States
     ...    button[aria-label="Switch between dark and light mode (currently dark mode)"]