From e6dd623ded829795477acf4cd2a8f331eb45bb4e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=BCrgen=20Gmach?= <juergen.gmach@canonical.com>
Date: Wed, 11 Feb 2026 17:28:44 +0100
Subject: [PATCH] Add option to skip removed URLs check

Allow users to skip the removed URLs check by including
'skip removed-urls-check' in the PR title, PR body, or commit message.
This is useful when intentionally removing pages or when redirects
will be added in a follow-up commit.

Added a how-to guide explaining how to use this feature with
an example commit message.

Fixes #531
---
 .github/workflows/check-removed-urls.yml |  4 +++
 docs/how-to/index.rst                    |  1 +
 docs/how-to/skip-removed-urls-check.rst  | 40 ++++++++++++++++++++++++
 3 files changed, 45 insertions(+)
 create mode 100644 docs/how-to/skip-removed-urls-check.rst

diff --git a/.github/workflows/check-removed-urls.yml b/.github/workflows/check-removed-urls.yml
index cfb6b4d4..bb370612 100644
--- a/.github/workflows/check-removed-urls.yml
+++ b/.github/workflows/check-removed-urls.yml
@@ -8,6 +8,10 @@ on:
 jobs:
   build-docs:
     runs-on: ubuntu-latest
+    if: |
+      !contains(github.event.pull_request.title, 'skip check-removed-urls') &&
+      !contains(github.event.pull_request.body, 'skip check-removed-urls') &&
+      !contains(github.event.head_commit.message, 'skip check-removed-urls')
     steps:
       - name: Checkout PR branch
         uses: actions/checkout@v5
diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst
index b786d080..7d1ebe2c 100644
--- a/docs/how-to/index.rst
+++ b/docs/how-to/index.rst
@@ -25,6 +25,7 @@ Set up, configure, upgrade, and customize your project to keep it organized and
     migrate-from-pre-extension
     update
     troubleshoot-issues
+    skip-removed-urls-check
 
 Optional features and workflows
 -------------------------------
diff --git a/docs/how-to/skip-removed-urls-check.rst b/docs/how-to/skip-removed-urls-check.rst
new file mode 100644
index 00000000..c9c8c315
--- /dev/null
+++ b/docs/how-to/skip-removed-urls-check.rst
@@ -0,0 +1,40 @@
+.. _skip-removed-urls-check:
+
+Skip the removed URLs check
+============================
+
+The starter pack includes an automatic check that verifies no URLs are removed when you make changes to your documentation.
+This helps prevent broken links when pages are removed without proper redirects.
+
+However, in some cases you may want to intentionally skip this check, for example when:
+
+* You are removing deprecated pages that are no longer relevant
+* You are restructuring documentation and will add redirects in a follow-up commit
+* You are working on a draft PR and will address URL changes later
+
+How to skip the check
+---------------------
+
+To skip the removed URLs check, include the text ``skip removed-urls-check`` in one of the following places:
+
+* The pull request title
+* The pull request body/description
+* A commit message
+
+Example commit
+--------------
+
+Here's an example of a commit message that will skip the removed URLs check::
+
+  Remove outdated installation guide
+
+  The old installation instructions are no longer relevant
+  after the new unified setup process was introduced.
+
+  skip removed-urls-check
+
+When you push this commit and create a pull request, the removed URLs check workflow will be skipped automatically.
+
+.. note::
+   Use this feature responsibly. Removing URLs without proper redirects can lead to broken links and a poor user experience.
+   Make sure you have a valid reason to skip the check.