diff --git a/.woodpecker/docs.yaml b/.woodpecker/docs.yaml
index 583560aca44..abbb95d6dc6 100644
--- a/.woodpecker/docs.yaml
+++ b/.woodpecker/docs.yaml
@@ -50,7 +50,7 @@ steps:
   build-cli:
     image: *golang_image
     commands:
-      - make docs
+      - make generate-docs
     when:
       - path: *when_path
         event: [tag, pull_request, push]
diff --git a/Makefile b/Makefile
index a9cf6bb42de..ddbd0805e78 100644
--- a/Makefile
+++ b/Makefile
@@ -337,9 +337,17 @@ spellcheck:
 	  pnpx cspell lint --no-progress stdin
 
 ##@ Docs
-.PHONY: docs
-docs: ## Generate docs (currently only for the cli)
+.PHONY: docs-dependencies
+docs-dependencies: ## Install docs dependencies
+	(cd docs/; pnpm install --frozen-lockfile)
+
+.PHONY: generate-docs
+generate-docs: ## Generate docs (currently only for the cli)
 	CGO_ENABLED=0 go generate cmd/cli/app.go
 	CGO_ENABLED=0 go generate cmd/server/openapi.go
 
+.PHONY: build-docs
+build-docs: generate-docs docs-dependencies ## Build the docs
+	(cd docs/; pnpm build)
+
 endif
diff --git a/docs/docs/92-development/09-openapi.md b/docs/docs/92-development/09-openapi.md
index 1d7e5853327..8fc63d87377 100644
--- a/docs/docs/92-development/09-openapi.md
+++ b/docs/docs/92-development/09-openapi.md
@@ -55,5 +55,5 @@ make generate-openapi
 ```
 
 ```bash title="update the Markdown in the ./docs folder"
-make docs
+make generate-docs
 ```
diff --git a/docs/package.json b/docs/package.json
index cca63f5fa51..0c79e4b8305 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -3,7 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "start": "cd ../ && make docs && cd docs && docusaurus start",
+    "start": "cd ../ && make generate-docs && cd docs && docusaurus start",
     "build": "pnpm build:woodpecker-plugins && docusaurus build",
     "build:woodpecker-plugins": "cd plugins/woodpecker-plugins && pnpm i && pnpm build",
     "swizzle": "docusaurus swizzle",
diff --git a/docs/versioned_docs/version-1.0/92-development/08-swagger.md b/docs/versioned_docs/version-1.0/92-development/08-swagger.md
index 4dd7250a730..59c53739f4e 100644
--- a/docs/versioned_docs/version-1.0/92-development/08-swagger.md
+++ b/docs/versioned_docs/version-1.0/92-development/08-swagger.md
@@ -61,7 +61,7 @@ make generate-swagger
 ##### update the Markdown in the ./docs folder
 
 ```shell
-make docs
+make generate-docs
 ```
 
 ##### auto-format swagger related godoc
diff --git a/docs/versioned_docs/version-2.6/92-development/08-swagger.md b/docs/versioned_docs/version-2.6/92-development/08-swagger.md
index 9a3775c4139..7f5c5354ebf 100644
--- a/docs/versioned_docs/version-2.6/92-development/08-swagger.md
+++ b/docs/versioned_docs/version-2.6/92-development/08-swagger.md
@@ -55,7 +55,7 @@ make generate-swagger
 ```
 
 ```bash title="update the Markdown in the ./docs folder"
-make docs
+make generate-docs
 ```
 
 ```bash title="auto-format swagger related godoc"
diff --git a/docs/versioned_docs/version-2.7/92-development/09-swagger.md b/docs/versioned_docs/version-2.7/92-development/09-swagger.md
index 5bf303c7b48..e167c4aed61 100644
--- a/docs/versioned_docs/version-2.7/92-development/09-swagger.md
+++ b/docs/versioned_docs/version-2.7/92-development/09-swagger.md
@@ -55,7 +55,7 @@ make generate-swagger
 ```
 
 ```bash title="update the Markdown in the ./docs folder"
-make docs
+make generate-docs
 ```
 
 ```bash title="auto-format swagger related godoc"
diff --git a/docs/versioned_docs/version-2.8/92-development/09-swagger.md b/docs/versioned_docs/version-2.8/92-development/09-swagger.md
index 9a3775c4139..7f5c5354ebf 100644
--- a/docs/versioned_docs/version-2.8/92-development/09-swagger.md
+++ b/docs/versioned_docs/version-2.8/92-development/09-swagger.md
@@ -55,7 +55,7 @@ make generate-swagger
 ```
 
 ```bash title="update the Markdown in the ./docs folder"
-make docs
+make generate-docs
 ```
 
 ```bash title="auto-format swagger related godoc"