Fix markdown linting errors (#112)

* Fix minor markdown liniting errors

* Fix remaining markdown linting errors with Claude

* Use callouts for warnings in deprecated metric providers

* Fix linting error - regex of container name

* Add CONTRIBUTING.md - how to add a pre-commit hook for auto-linting

Author: davidkopp

CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+We are super happy if you are interested in contributing to the documentation of the Green Metrics Tool.
+
+All contributions should be done via Pull Requests. We use the standard forking workflow for Pull Requests. If you are not familiar with forks, you can find more information e.g. in [GitHub's documentation](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project)
+
+## Lint
+
+We use [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) for linting the content of the documentation.
+
+To check if the content has linting issues you can call
+
+```sh
+npm run lint:markdown
+```
+
+in the project directory.
+
+To automatically resolve fixable issues, use
+
+```sh
+npm run lint:markdown-fix
+```
+
+We recommend that you set a pre-commit hook to lint and fix issues automatically every time you commit. This can be done by adding
+
+```sh
+npm run lint:markdown-fix:staged
+```
+
+to a file named `./.git/hooks/pre-commit` and making it executable `chmod +x ./.git/hooks/pre-commit`

content/en/docs/cluster/accuracy-control.md

@@ -11,6 +11,7 @@ When using the *client* mode the cluster expects a *Measurement Control Workload
 This is done by running a defined workload and checking the standard deviation over a defined window of measurements.
 
 We recommend having your machines setup with our [NOP Linux changes →]({{< relref "nop-linux" >}}) and utilize the following setting by using our provided control workload:
+
 ```yml
 cluster:
   client:
@@ -63,6 +64,4 @@ cluster:
   + `phase` **[str]**: The phase to look at. default is *004_[RUNTIME]*. We do not recommend to change this unless you have a custom defined phase you want to look at.
   + `metrics` **[dict]**: Contains a dictionary of all the metrics you want to check the STDDEV or relative STDDEV. Every metric is looked at individually and if the thresshold is exceeded of any of them the cluster will pause further job processing. Checks can be either relative or absolute. We recommend using relative where possible and absolute only of you very small values for the relevant metric and even small changes will lead to high relative changes. We further recommend using the default set as defined above if you have these metric providers enabled. If you do not have these providers available we recommend choosing at least one `psu_energy_...` provider that actually measures and does not estimation. The names are found in the *Metric Name* section of the respective metric provider.\
   Example: [RAPL CPU →]({{< relref "/docs/measuring/metric-providers/cpu-energy-RAPL-MSR-component" >}}) is `cpu_energy_rapl_msr_component`
-  
-
-
+  

content/en/docs/cluster/cron-jobs.md

@@ -12,7 +12,7 @@ They must be run periodically through an external trigger, for instance through
 
 This page provides examples how we setup the *cron jobs*. Adjust the times and frequency to your needs.
 
-```
+```bash
 # m h  dom mon dow   command
 SHELL=/bin/bash
 

content/en/docs/cluster/installation.md

@@ -52,6 +52,7 @@ WantedBy=default.target
 ```
 
 Then activate the service
+
 ```bash
 systemctl --user daemon-reload # Reload the systemd configuration
 systemctl --user enable green-coding-client # enable on boot
@@ -78,6 +79,7 @@ sudo chmod 500 /etc/sudoers.d/green-coding-cluster-cleanup
 The Green Metrics Tool comes with an implemented queueing and locking mechanism. In contrast to the NOP Linux implementation this way of checking for jobs doesn't poll with a process all the time but relies on cron which is not available on NOP Linux.
 
 You can install a cronjob on your system to periodically call:
+
 - `python3 -u PATH_TO_GREEN_METRICS_TOOL/tools/jobs.py project` to measure projects in database queue
 - `python3 -u PATH_TO_GREEN_METRICS_TOOL/tools/jobs.py email` to send all emails in the database queue
 
@@ -105,6 +107,7 @@ machine:
   base_temperature_chip: "coretemp-isa-0000"
   base_temperature_feature: "Package id 0"
 ```
+
 The `id` and the `description` must be unique so that they do not conflict with the other machines in the cluster.
 
 If you are using the *NOP Linux* setup with the `client.py` service you must also setup the temperature checking. Find out what your system has when it is cool. You can either use our calibration script or just let the machine sit for a while until the temperature does not change anymore. Then set the value `base_temperature_value`. It has no unit, but is rather just a value in degree (°). It should have the same unit as your output of `sensors` on your Linux box.
@@ -114,14 +117,14 @@ Since we are using our [lm_sensors provider →]({{< relref "/docs/measuring/met
 #### Profiling Machines
 
 Machines that are intended to create a carbon profile *as it would be seen in a user machine* should have:
+
 - Turbo Boost turned on
 - Hyper Threading turned on
 - DVFS turned on
 - Allow C8-C0 states
 
 This is the minium set we deem reasonable. Please note that this resembles a user machine the best. For server machines some of these configurations should be changed. For servers Hyper Threading is often turned on whereas DVFS is often turned off.
 
-
 #### Benchmarking Machines
 
 To have the most stable result benchmarking machines or if you want to use Container Energy Estimations based on CPU Utilization you should have:
@@ -133,7 +136,7 @@ To have the most stable result benchmarking machines or if you want to use Conta
 
 All of these settings can be tweaked best in the BIOS. Additionally for turning DVFS off we recommend booting the kernel with `intel_pstate` CPU frequency driver deactived and using the `acpi` one which allows for setting the `userspace` govenor.
 
-```
+```bash
 $ sudo nano /etc/default/grub
 
 # Change this line
@@ -174,4 +177,3 @@ The GMT refers to *client* when it is talking about the settings for the `client
 When using the *client* mode the cluster expects a *Measurement Control Workload* to be set to determine if the cluster accuracy has deviated from the expected baseline.
 
 Please see [Accuracy Control →]({{< relref "accuracy-control" >}}) for details.
-

content/en/docs/cluster/nop-linux.md

@@ -13,7 +13,7 @@ We recommend tuning the Linux OS on all linux measurement machines that you have
 The following script configures an Ubuntu 22.04+ system to have no active timers running, remove all unneeded services and disable also
 NTP.
 
-The goal is to keep the system still very close to a production / user setup, but remove invariances from the system without 
+The goal is to keep the system still very close to a production / user setup, but remove invariances from the system without
 decreasing idle power draw and skewing results.
 
 Please further note that you must execute certain service still periodically. The [client.py](https://github.com/green-coding-solutions/green-metrics-tool/blob/main/cron/client.py) cluster service will periodically run [a cleanup script](https://github.com/green-coding-solutions/green-metrics-tool/blob/main/tools/cluster/cleanup_original.py)
@@ -159,4 +159,4 @@ else
 fi
 
 echo "All done. Please reboot system!"
-```
+```

content/en/docs/cluster/observability.md

@@ -29,8 +29,9 @@ To provide insights and execute net-gain analysis we provide an extension to the
 In essence it is an aggregate dashboard that gathers all energy and carbon data from our tools that submit their data to the GMT API.
 
 In the *CarbonDB Dashboard* you can find:
+
 - CI/CD energy and carbon data from Eco-CI
 - Benchmarking energy and carbon data from Green Metrics Tool runs
 - Developer machine energy and carbon data from PowerHOG
-- Custom energy and carbon data from [CarbonDB Agents](https://github.com/green-coding-solutions/carbondb-agent) configured 
-    - A typical setup for instance is to install a [CarbonDB Agent](https://github.com/green-coding-solutions/carbondb-agent) on the database server as well as the Frontend / Dashboard server
+- Custom energy and carbon data from [CarbonDB Agents](https://github.com/green-coding-solutions/carbondb-agent) configured
+  - A typical setup for instance is to install a [CarbonDB Agent](https://github.com/green-coding-solutions/carbondb-agent) on the database server as well as the Frontend / Dashboard server

content/en/docs/cluster/power-saving.md

@@ -11,7 +11,7 @@ When the cluster is setup it is often not needed to have the machines powered wh
 
 What you can setup is a simple Wake-on-LAN script that will only wakeup the machines when there is job in the queue waiting.
 
-For examplary purposes we document a script here that works on a low power *Raspberry PI* that we have active in our 
+For examplary purposes we document a script here that works on a low power *Raspberry PI* that we have active in our
 local network, but any simple microcontroller that has HTTP capabilites will.
 
 ```bash
@@ -45,6 +45,7 @@ fi
 ```
 
 ### Turning machine off on empty queue
+
 To use this functionality you should have *Wake-on-LAN* activated.
 
 You can then set the `shutdown_on_job_no` to either "*poweroff*" or "*suspend*" and the machine will turn off when the job queue is empty.
@@ -60,6 +61,7 @@ In order for the shutdown to be triggered by the `client.py` you must allow the
 Please choose the line that is appropriate for you depending on if you want to suspend or poweroff.
 
 Example:
+
 ```bash
 echo 'ALL ALL=(ALL) NOPASSWD:/usr/bin/systemctl suspend' | sudo tee /etc/sudoers.d/green-coding-shutdown # for systems that support suspend
 echo 'ALL ALL=(ALL) NOPASSWD:/usr/bin/systemctl poweroff' | sudo tee -a /etc/sudoers.d/green-coding-shutdown # for systems that only can shutdown
@@ -71,6 +73,7 @@ sudo chmod 500 /etc/sudoers.d/green-coding-shutdown
 In rare circumstances Wake-On-Lan is not active on the machine.
 
 Check the following:
+
 - Check the BIOS if Wake-On-Lan is enabled.
   + If no option is present it might not be configurable through the BIOS
 - Check `$ sudo ethtool <YOUR_INTERFACE>`
@@ -106,6 +109,7 @@ Check `$ cat /sys/power/state`. It should list `mem` as part of the output.
 This means the OS supports bringing the system to *Suspend to RAM*.
 
 Now check `$ cat /sys/power/mem_sleep`. A sample output looks like this:
+
 ```log
 s2idle [deep]
 ```

content/en/docs/cluster/security.md

@@ -18,7 +18,7 @@ We recommend having the default user active for the API to only have *SELECT* an
 
 That way if your are victim to an SQL injection or code injection the resulting injection cannot modifiy existing data.
 
-```
+```sql
 CREATE USER manager WITH PASSWORD 'YOUR_PASSWORD';
 
 REVOKE ALL PRIVILEGES ON DATABASE "green-coding" FROM manager;
@@ -64,7 +64,7 @@ GRANT USAGE, SELECT ON SEQUENCE jobs_new_id_seq TO manager;
 GRANT SELECT, INSERT ON TABLE jobs TO manager;
 ```
 
-To complement the configuration you need also have a different `config.yml` file present to read the credentials from. 
+To complement the configuration you need also have a different `config.yml` file present to read the credentials from.
 
 You need to create a file called `manager-config.yml` in the GMT root directory, which will automatically be picked up by the cron jobs in `./cron/`
 
@@ -94,7 +94,7 @@ Since a rogue user can always escape from the docker container and infiltrate th
 
 We recommend NOT to have SMTP credentials on the machines and also connect to the database with a very restrcted user.
 
-```
+```sql
 CREATE USER client WITH PASSWORD 'YOUR_PASSWORD';
 REVOKE ALL PRIVILEGES ON ALL TABLES IN SCHEMA public FROM client;
 

content/en/docs/cluster/user-management.md

@@ -6,6 +6,7 @@ weight: 1005
 ---
 
 In the FOSS version of GMT only two base users are configured and every action can be executed with them:
+
 - USER 1 - The default user
 - USER 0 - The GMT system user running control workloads and sending e-mails
 
@@ -29,11 +30,12 @@ Here is an example cURL request:
          -H "X-Authentication: ${API_TOKEN}"
 ```
 
-**Important:** If no *X-Authentication* header is supplied the API will still authenticate *USER 1* by default. 
+**Important:** If no *X-Authentication* header is supplied the API will still authenticate *USER 1* by default.
 
 ## Features of User Management
 
 For complex usage cases GMT comes with a user management system that allows:
+
 - Restricting certain routes to view content (GET)
 - Restricting certain routes for submission of measurements, CI runs, Hog Data etc. (POST)
 - Allowing longer / shorter data retention times for certain users
@@ -47,4 +49,4 @@ For complex usage cases GMT comes with a user management system that allows:
 Please note that the user management system is bundled with GMT but managed and fully documented as part of the [Enterprise](https://www.green-coding.io/products/green-metrics-tool/) package.
 Furthermore many features like needed maintenance jobs / cron jobs and ACL generators are only shipped with the [Enterprise](https://www.green-coding.io/products/green-metrics-tool/) version.
 
-We believe that user management is only needed in bigger corporate settings and thus we encourage you to support this project by considering upgrading to a [paid version](https://www.green-coding.io/products/green-metrics-tool) which includes the User Management either included in the SaaS version or the Enterprise version.
+We believe that user management is only needed in bigger corporate settings and thus we encourage you to support this project by considering upgrading to a [paid version](https://www.green-coding.io/products/green-metrics-tool) which includes the User Management either included in the SaaS version or the Enterprise version.

content/en/docs/declarations/export-formats.md

@@ -20,4 +20,3 @@ All data is exposed through API endpoints documented for local installs under [h
 or if you use the hosted service under [https://api.green-coding.io](https://api.green-coding.io).
 
 By issueing *GET* queries to the relevant endpoints all data can be exported as *JSON* format.
-