ci(docs): add markdownlint foundation (prek + CI)

.github/workflows/markdown-lint.yml

@@ -0,0 +1,60 @@
+name: 'Docs: Markdown Lint'
+
+on:
+  push:
+    branches:
+      - 'master'
+      - 'v5.*'
+  pull_request:
+    branches:
+      - 'master'
+      - 'v5.*'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  markdown-lint:
+    if: github.repository == 'prowler-cloud/prowler'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@fa2e9d605c4eeb9fcad4c99c224cee0c6c7f3594 # v2.16.0
+        with:
+          egress-policy: block
+          allowed-endpoints: >
+            api.github.com:443
+            github.com:443
+            registry.npmjs.org:443
+            release-assets.githubusercontent.com:443
+
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version-file: ui/.nvmrc
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+        with:
+          package_json_file: ui/package.json
+          run_install: false
+
+      - name: Run markdownlint
+        # Pin must match .pre-commit-config.yaml so prek and CI behave identically.
+        # pnpm dlx doesn't accept --ignore-scripts as a flag; the env var
+        # disables postinstall scripts on transitives the same way.
+        env:
+          pnpm_config_ignore_scripts: 'true'
+        run: pnpm dlx markdownlint-cli@0.45.0 '**/*.md'

.markdownlint.json

@@ -0,0 +1,10 @@
+{
+  "extends": "markdownlint/style/prettier",
+  "first-line-h1": false,
+  "no-duplicate-heading": {
+    "siblings_only": true
+  },
+  "no-inline-html": false,
+  "line-length": false,
+  "no-bare-urls": false
+}

.markdownlintignore

@@ -0,0 +1,16 @@
+node_modules/
+ui/node_modules/
+.git/
+.venv/
+**/.venv/
+dist/
+build/
+htmlcov/
+.next/
+ui/.next/
+ui/out/
+contrib/
+
+# Auto-generated content (keepachangelog format legitimately repeats section headings).
+# Revisit with the team — see beads task on markdownlint rule triage.
+**/CHANGELOG.md

.pre-commit-config.yaml

@@ -133,6 +133,13 @@ repos:
         pass_filenames: false
         priority: 50
 
+  ## MARKDOWN
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.45.0
+    hooks:
+      - id: markdownlint
+        priority: 30
+
   ## CONTAINERS
   - repo: https://github.com/hadolint/hadolint
     rev: v2.14.0

AGENTS.md

@@ -11,6 +11,7 @@
 Use these skills for detailed patterns on-demand:
 
 ### Generic Skills (Any Project)
+
 | Skill | Description | URL |
 |-------|-------------|-----|
 | `typescript` | Const types, flat interfaces, utility types | [SKILL.md](skills/typescript/SKILL.md) |
@@ -28,6 +29,7 @@ Use these skills for detailed patterns on-demand:
 | `tdd` | Test-Driven Development workflow | [SKILL.md](skills/tdd/SKILL.md) |
 
 ### Prowler-Specific Skills
+
 | Skill | Description | URL |
 |-------|-------------|-----|
 | `prowler` | Project overview, component navigation | [SKILL.md](skills/prowler/SKILL.md) |

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Do you want to learn on how to...
+# Do you want to learn on how to
 
 - [Contribute with your code or fixes to Prowler](https://docs.prowler.com/developer-guide/introduction)
 - [Create a new provider](https://docs.prowler.com/developer-guide/provider)
@@ -32,5 +32,6 @@ Provider-specific developer notes:
 
 Want some swag as appreciation for your contribution?
 
-# Prowler Developer Guide
-https://goto.prowler.com/devguide
+## Prowler Developer Guide
+
+<https://goto.prowler.com/devguide>

README.md

@@ -1,6 +1,6 @@
 <p align="center">
-  <img align="center" src="https://github.com/prowler-cloud/prowler/blob/master/docs/img/prowler-logo-black.png#gh-light-mode-only" width="50%" height="50%">
-  <img align="center" src="https://github.com/prowler-cloud/prowler/blob/master/docs/img/prowler-logo-white.png#gh-dark-mode-only" width="50%" height="50%">
+  <img align="center" alt="Prowler logo" src="https://github.com/prowler-cloud/prowler/blob/master/docs/img/prowler-logo-black.png#gh-light-mode-only" width="50%" height="50%">
+  <img align="center" alt="Prowler logo" src="https://github.com/prowler-cloud/prowler/blob/master/docs/img/prowler-logo-white.png#gh-dark-mode-only" width="50%" height="50%">
 </p>
 <p align="center">
   <b><i>Prowler</b> is the Open Cloud Security Platform trusted by thousands to automate security and compliance in any cloud environment. With hundreds of ready-to-use checks and compliance frameworks, Prowler delivers real-time, customizable monitoring and seamless integrations, making cloud security simple, scalable, and cost-effective for organizations of any size.
@@ -22,8 +22,8 @@
   <a href="https://pypistats.org/packages/prowler"><img alt="PyPI Downloads" src="https://img.shields.io/pypi/dw/prowler.svg?label=downloads"></a>
   <a href="https://hub.docker.com/r/toniblyx/prowler"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/toniblyx/prowler"></a>
   <a href="https://gallery.ecr.aws/prowler-cloud/prowler"><img width="120" height=19" alt="AWS ECR Gallery" src="https://user-images.githubusercontent.com/3985464/151531396-b6535a68-c907-44eb-95a1-a09508178616.png"></a>
-  <a href="https://codecov.io/gh/prowler-cloud/prowler"><img src="https://codecov.io/gh/prowler-cloud/prowler/graph/badge.svg?token=OflBGsdpDl"/></a>
-  <a href="https://insights.linuxfoundation.org/project/prowler-cloud-prowler"><img src="https://insights.linuxfoundation.org/api/badge/health-score?project=prowler-cloud-prowler"/></a>
+  <a href="https://codecov.io/gh/prowler-cloud/prowler"><img alt="Codecov coverage" src="https://codecov.io/gh/prowler-cloud/prowler/graph/badge.svg?token=OflBGsdpDl"/></a>
+  <a href="https://insights.linuxfoundation.org/project/prowler-cloud-prowler"><img alt="Linux Foundation insights health score" src="https://insights.linuxfoundation.org/api/badge/health-score?project=prowler-cloud-prowler"/></a>
 </p>
 <p align="center">
     <a href="https://github.com/prowler-cloud/prowler/releases"><img alt="Version" src="https://img.shields.io/github/v/release/prowler-cloud/prowler"></a>
@@ -36,7 +36,7 @@
 </p>
 <hr>
 <p align="center">
-  <img align="center" src="/docs/img/prowler-cloud.gif" width="100%" height="100%">
+  <img align="center" alt="Prowler Cloud demo" src="/docs/img/prowler-cloud.gif" width="100%" height="100%">
 </p>
 
 # Description
@@ -146,11 +146,11 @@ Prowler App offers flexible installation methods tailored to various environment
 
 ### Docker Compose
 
-**Requirements**
+#### Requirements
 
-* `Docker Compose` installed: https://docs.docker.com/compose/install/.
+- `Docker Compose` installed: https://docs.docker.com/compose/install/.
 
-**Commands**
+#### Commands
 
 ``` console
 VERSION=$(curl -s https://api.github.com/repos/prowler-cloud/prowler/releases/latest | jq -r .tag_name)
@@ -175,14 +175,14 @@ You can find more information in the [Troubleshooting](./docs/troubleshooting.md
 
 ### From GitHub
 
-**Requirements**
+#### Requirements
 
-* `git` installed.
-* `uv` installed: [uv installation](https://docs.astral.sh/uv/getting-started/installation/).
-* `pnpm` installed: [pnpm installation](https://pnpm.io/installation).
-* `Docker Compose` installed: https://docs.docker.com/compose/install/.
+- `git` installed.
+- `uv` installed: [uv installation](https://docs.astral.sh/uv/getting-started/installation/).
+- `pnpm` installed: [pnpm installation](https://pnpm.io/installation).
+- `Docker Compose` installed: https://docs.docker.com/compose/install/.
 
-**Commands to run the API**
+#### Commands to run the API
 
 ``` console
 git clone https://github.com/prowler-cloud/prowler
@@ -199,7 +199,7 @@ gunicorn -c config/guniconf.py config.wsgi:application
 
 > After completing the setup, access the API documentation at http://localhost:8080/api/v1/docs.
 
-**Commands to run the API Worker**
+#### Commands to run the API Worker
 
 ``` console
 git clone https://github.com/prowler-cloud/prowler
@@ -212,7 +212,7 @@ cd src/backend
 python -m celery -A config.celery worker -l info -E
 ```
 
-**Commands to run the API Scheduler**
+#### Commands to run the API Scheduler
 
 ``` console
 git clone https://github.com/prowler-cloud/prowler
@@ -225,7 +225,7 @@ cd src/backend
 python -m celery -A config.celery beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler
 ```
 
-**Commands to run the UI**
+#### Commands to run the UI
 
 ``` console
 git clone https://github.com/prowler-cloud/prowler
@@ -237,7 +237,7 @@ pnpm start
 
 > Once configured, access the Prowler App at http://localhost:3000. Sign up using your email and password to get started.
 
-**Pre-commit Hooks Setup**
+#### Pre-commit Hooks Setup
 
 Some pre-commit hooks require tools installed on your system:
 
@@ -257,14 +257,14 @@ prowler -v
 
 ### Containers
 
-**Available Versions of Prowler CLI**
+#### Available Versions of Prowler CLI
 
 The following versions of Prowler CLI are available, depending on your requirements:
 
 - `latest`: Synchronizes with the `master` branch. Note that this version is not stable.
 - `v4-latest`: Synchronizes with the `v4` branch. Note that this version is not stable.
 - `v3-latest`: Synchronizes with the `v3` branch. Note that this version is not stable.
-- `<x.y.z>` (release): Stable releases corresponding to specific versions. You can find the complete list of releases [here](https://github.com/prowler-cloud/prowler/releases).
+- `<x.y.z>` (release): Stable releases corresponding to specific versions. See the [complete list of Prowler releases](https://github.com/prowler-cloud/prowler/releases).
 - `stable`: Always points to the latest release.
 - `v4-stable`: Always points to the latest release for v4.
 - `v3-stable`: Always points to the latest release for v3.
@@ -338,7 +338,7 @@ Full configuration, per-provider authentication, and SARIF examples: [Prowler Gi
 
 ## Prowler CLI
 
-**Running Prowler**
+### Running Prowler
 
 Prowler can be executed across various environments, offering flexibility to meet your needs. It can be run from:
 

api/AGENTS.md

@@ -10,7 +10,7 @@
 > - [`jsonapi`](../skills/jsonapi/SKILL.md) - Strict JSON:API v1.1 spec compliance
 > - [`pytest`](../skills/pytest/SKILL.md) - Generic pytest patterns
 
-### Auto-invoke Skills
+## Auto-invoke Skills
 
 When performing these actions, ALWAYS invoke the corresponding skill FIRST:
 
@@ -81,15 +81,15 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST:
 ## DECISION TREES
 
 ### Serializer Selection
-```
+```text
 Read → <Model>Serializer
 Create → <Model>CreateSerializer
 Update → <Model>UpdateSerializer
 Nested read → <Model>IncludeSerializer
 ```
 
 ### Task vs View
-```
+```text
 < 100ms → View
 > 100ms or external API → Celery task
 Needs retry → Celery task
@@ -105,7 +105,7 @@ Django 5.1.x | DRF 3.15.x | djangorestframework-jsonapi 7.x | Celery 5.4.x | Pos
 
 ## PROJECT STRUCTURE
 
-```
+```text
 api/src/backend/
 ├── api/                    # Main Django app
 │   ├── v1/                # API version 1 (views, serializers, urls)