diff --git a/.gitlab/ci/docs.yml b/.gitlab/ci/docs.yml
index 8968245..4cc8bfe 100644
--- a/.gitlab/ci/docs.yml
+++ b/.gitlab/ci/docs.yml
@@ -1,5 +1,5 @@
 variables:
-  ESP_IDF_DOC_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.2:1-1"
+  ESP_IDF_DOC_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.4:1-1"
 
 .build_docs_template:
   image: $ESP_IDF_DOC_ENV_IMAGE
diff --git a/.gitlab/ci/pre_check.yml b/.gitlab/ci/pre_check.yml
index 38842dd..ccbda4f 100644
--- a/.gitlab/ci/pre_check.yml
+++ b/.gitlab/ci/pre_check.yml
@@ -5,3 +5,23 @@ check_readme_links:
   allow_failure: true
   script:
     - python ${CI_PROJECT_DIR}/tools/ci/check_readme_links.py
+
+check_doc_links:
+  stage: pre_check
+  image: $ESP_DOCS_ENV_IMAGE
+  tags: [check_doc_links]
+  variables:
+    DOCS_DIR: $CI_PROJECT_DIR/docs
+  allow_failure: true
+  rules:
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'  # Run for all changes to a merge request's source branch
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH       # Run for all changes to the default branch
+  script:
+    - cd docs
+    - cd $DOCS_DIR
+    - pip install -r requirements.txt
+    - build-docs -t $DOCTGT -l $DOCLANG linkcheck
+  parallel:
+    matrix:
+      - DOCLANG: ["en", "zh_CN"]
+        DOCTGT: ['esp32', 'esp32s2', 'esp32s3', 'esp32c3', 'esp32c6', 'esp32h2', 'esp32c2', 'esp32p4', 'esp32c5', 'esp32c61', 'other']
\ No newline at end of file
diff --git a/docs/conf_common.py b/docs/conf_common.py
index 55cf1a2..0aa9821 100755
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -137,3 +137,9 @@
 # Measurement ID for Google Analytics
 
 google_analytics_id = 'G-6GCDQQ87G0'
+
+# disable the check for link anchors
+linkcheck_anchors = False
+
+linkcheck_exclude_documents = ['index',  # several false positives due to the way we link to different sections
+                                ]
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 2bade19..d85c588 100755
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1 +1 @@
-esp-docs>=1.11.0
+esp-docs==1.12.0