add lychee: ci test for 404s in docs (#14440)

paulOsinski · web-flow · commit 00711615c935 · 2026-03-11T08:12:57.000+01:00
* implement lychee

* pass unit tests

* update contribution guidelines for docs
diff --git a/.github/workflows/validate_docs_build.yml b/.github/workflows/validate_docs_build.yml
@@ -40,3 +40,10 @@ jobs:
           HUGO_ENVIRONMENT: production
           HUGO_ENV: production
         run: cd docs && npm ci && hugo --minify --gc --config config/production/hugo.toml
+
+      - name: Check internal links
+        uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2
+        with:
+          args: --offline --no-progress --root-dir docs/public './docs/public/**/*.html'
+          fail: true
+
diff --git a/docs/content/admin/sso/OS__auth0.md b/docs/content/admin/sso/OS__auth0.md
@@ -5,7 +5,7 @@ weight: 4
 audience: opensource
 ---
 
-Open-Source DefectDojo supports login via Auth0. DefectDojo Pro users should refer to the [Pro Auth0 guide](../PRO__auth0/).
+Open-Source DefectDojo supports login via Auth0. DefectDojo Pro users should refer to the [Pro Auth0 guide](/admin/sso/pro__auth0/).
 
 ## Prerequisites
 
diff --git a/docs/content/admin/sso/OS__azure_ad.md b/docs/content/admin/sso/OS__azure_ad.md
@@ -5,7 +5,7 @@ weight: 6
 audience: opensource
 ---
 
-Open-Source DefectDojo supports login via Azure Active Directory (Azure AD), including automatic User Group synchronization. DefectDojo Pro users should refer to the [Pro Azure AD guide](../PRO__azure_ad/).
+Open-Source DefectDojo supports login via Azure Active Directory (Azure AD), including automatic User Group synchronization. DefectDojo Pro users should refer to the [Pro Azure AD guide](/admin/sso/pro__azure_ad/).
 
 ## Prerequisites
 
diff --git a/docs/content/admin/sso/OS__github_enterprise.md b/docs/content/admin/sso/OS__github_enterprise.md
@@ -5,7 +5,7 @@ weight: 8
 audience: opensource
 ---
 
-Open-Source DefectDojo supports login via GitHub Enterprise. DefectDojo Pro users should refer to the [Pro GitHub Enterprise guide](../PRO__github_enterprise/).
+Open-Source DefectDojo supports login via GitHub Enterprise. DefectDojo Pro users should refer to the [Pro GitHub Enterprise guide](/admin/sso/pro__github_enterprise/).
 
 ## Prerequisites
 
diff --git a/docs/content/admin/sso/OS__gitlab.md b/docs/content/admin/sso/OS__gitlab.md
@@ -5,7 +5,7 @@ weight: 10
 audience: opensource
 ---
 
-Open-Source DefectDojo supports login via GitLab. DefectDojo Pro users should refer to the [Pro GitLab guide](../PRO__gitlab/).
+Open-Source DefectDojo supports login via GitLab. DefectDojo Pro users should refer to the [Pro GitLab guide](/admin/sso/pro__gitlab/).
 
 ## Prerequisites
 
diff --git a/docs/content/admin/sso/OS__google.md b/docs/content/admin/sso/OS__google.md
@@ -5,7 +5,7 @@ weight: 12
 audience: opensource
 ---
 
-Open-Source DefectDojo supports login via Google accounts. New users are created automatically on first login if they don't already exist. Existing DefectDojo users are matched to Google accounts by username (the portion before the `@` in their Google email). DefectDojo Pro users should refer to the [Pro Google guide](../PRO__google/).
+Open-Source DefectDojo supports login via Google accounts. New users are created automatically on first login if they don't already exist. Existing DefectDojo users are matched to Google accounts by username (the portion before the `@` in their Google email). DefectDojo Pro users should refer to the [Pro Google guide](/admin/sso/pro__google/).
 
 ## Prerequisites
 
diff --git a/docs/content/admin/sso/OS__keycloak.md b/docs/content/admin/sso/OS__keycloak.md
@@ -5,7 +5,7 @@ weight: 14
 audience: opensource
 ---
 
-Open-Source DefectDojo supports login via KeyCloak. DefectDojo Pro users should refer to the [Pro KeyCloak guide](../PRO__keycloak/).
+Open-Source DefectDojo supports login via KeyCloak. DefectDojo Pro users should refer to the [Pro KeyCloak guide](/admin/sso/pro__keycloak/).
 
 This guide assumes you already have a KeyCloak Realm configured. If not, see the [KeyCloak documentation](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/realms/create.html).
 
diff --git a/docs/content/admin/sso/OS__oidc.md b/docs/content/admin/sso/OS__oidc.md
@@ -5,7 +5,7 @@ weight: 18
 audience: opensource
 ---
 
-Open-Source DefectDojo supports login via a generic OpenID Connect (OIDC) provider. DefectDojo Pro users should refer to the [Pro OIDC guide](../PRO__oidc/).
+Open-Source DefectDojo supports login via a generic OpenID Connect (OIDC) provider. DefectDojo Pro users should refer to the [Pro OIDC guide](/admin/sso/pro__oidc/).
 
 ## Configuration
 
diff --git a/docs/content/admin/sso/OS__okta.md b/docs/content/admin/sso/OS__okta.md
@@ -5,7 +5,7 @@ weight: 16
 audience: opensource
 ---
 
-Open-Source DefectDojo supports login via Okta. DefectDojo Pro users should refer to the [Pro Okta guide](../PRO__okta/).
+Open-Source DefectDojo supports login via Okta. DefectDojo Pro users should refer to the [Pro Okta guide](/admin/sso/pro__okta/).
 
 ## Prerequisites
 
diff --git a/docs/content/admin/sso/OS__saml.md b/docs/content/admin/sso/OS__saml.md
@@ -7,7 +7,7 @@ aliases:
   - /en/working_with_findings/sla_configuration
 ---
 
-Open-Source DefectDojo supports SAML authentication via environment variables. DefectDojo Pro users should refer to the [Pro SAML guide](../PRO__saml/).
+Open-Source DefectDojo supports SAML authentication via environment variables. DefectDojo Pro users should refer to the [Pro SAML guide](/admin/sso/pro__saml/).
 
 ## Setup
 
diff --git a/docs/content/admin/sso/PRO__auth0.md b/docs/content/admin/sso/PRO__auth0.md
@@ -5,7 +5,7 @@ weight: 3
 audience: pro
 ---
 
-DefectDojo Pro supports login via Auth0. Open-Source users should refer to the [Open-Source Auth0 guide](../OS__auth0/).
+DefectDojo Pro supports login via Auth0. Open-Source users should refer to the [Open-Source Auth0 guide](/admin/sso/os__auth0/).
 
 ## Prerequisites
 
diff --git a/docs/content/admin/sso/PRO__azure_ad.md b/docs/content/admin/sso/PRO__azure_ad.md
@@ -5,7 +5,7 @@ weight: 5
 audience: pro
 ---
 
-DefectDojo Pro supports login via Azure Active Directory (Azure AD), including automatic User Group synchronization. Open-Source users should refer to the [Open-Source Azure AD guide](../OS__azure_ad/).
+DefectDojo Pro supports login via Azure Active Directory (Azure AD), including automatic User Group synchronization. Open-Source users should refer to the [Open-Source Azure AD guide](/admin/sso/os__azure_ad/).
 
 ## Prerequisites
 
diff --git a/docs/content/admin/sso/PRO__github_enterprise.md b/docs/content/admin/sso/PRO__github_enterprise.md
@@ -5,7 +5,7 @@ weight: 7
 audience: pro
 ---
 
-DefectDojo Pro supports login via GitHub Enterprise. Open-Source users should refer to the [Open-Source GitHub Enterprise guide](../OS__github_enterprise/).
+DefectDojo Pro supports login via GitHub Enterprise. Open-Source users should refer to the [Open-Source GitHub Enterprise guide](/admin/sso/os__github_enterprise/).
 
 ## Prerequisites
 
diff --git a/docs/content/admin/sso/PRO__gitlab.md b/docs/content/admin/sso/PRO__gitlab.md
@@ -5,7 +5,7 @@ weight: 9
 audience: pro
 ---
 
-DefectDojo Pro supports login via GitLab. Open-Source users should refer to the [Open-Source GitLab guide](../OS__gitlab/).
+DefectDojo Pro supports login via GitLab. Open-Source users should refer to the [Open-Source GitLab guide](/admin/sso/os__gitlab/).
 
 ## Prerequisites
 
diff --git a/docs/content/admin/sso/PRO__google.md b/docs/content/admin/sso/PRO__google.md
@@ -5,7 +5,7 @@ weight: 11
 audience: pro
 ---
 
-DefectDojo Pro supports login via Google accounts. New users are created automatically on first login if they don't already exist. Existing DefectDojo users are matched to Google accounts by username (the portion before the `@` in their Google email). Open-Source users should refer to the [Open-Source Google guide](../OS__google/).
+DefectDojo Pro supports login via Google accounts. New users are created automatically on first login if they don't already exist. Existing DefectDojo users are matched to Google accounts by username (the portion before the `@` in their Google email). Open-Source users should refer to the [Open-Source Google guide](/admin/sso/os__google/).
 
 ## Prerequisites
 
diff --git a/docs/content/admin/sso/PRO__keycloak.md b/docs/content/admin/sso/PRO__keycloak.md
@@ -5,7 +5,7 @@ weight: 13
 audience: pro
 ---
 
-DefectDojo Pro supports login via KeyCloak. Open-Source users should refer to the [Open-Source KeyCloak guide](../OS__keycloak/).
+DefectDojo Pro supports login via KeyCloak. Open-Source users should refer to the [Open-Source KeyCloak guide](/admin/sso/os__keycloak/).
 
 This guide assumes you already have a KeyCloak Realm configured. If not, see the [KeyCloak documentation](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/realms/create.html).
 
diff --git a/docs/content/admin/sso/PRO__oidc.md b/docs/content/admin/sso/PRO__oidc.md
@@ -5,7 +5,7 @@ weight: 17
 audience: pro
 ---
 
-DefectDojo Pro supports login via a generic OpenID Connect (OIDC) provider. Open-Source users should refer to the [Open-Source OIDC guide](../OS__oidc/).
+DefectDojo Pro supports login via a generic OpenID Connect (OIDC) provider. Open-Source users should refer to the [Open-Source OIDC guide](/admin/sso/os__oidc/).
 
 ## Configuration
 
diff --git a/docs/content/admin/sso/PRO__okta.md b/docs/content/admin/sso/PRO__okta.md
@@ -5,7 +5,7 @@ weight: 15
 audience: pro
 ---
 
-DefectDojo Pro supports login via Okta. Open-Source users should refer to the [Open-Source Okta guide](../OS__okta/).
+DefectDojo Pro supports login via Okta. Open-Source users should refer to the [Open-Source Okta guide](/admin/sso/os__okta/).
 
 ## Prerequisites
 
diff --git a/docs/content/admin/sso/PRO__saml.md b/docs/content/admin/sso/PRO__saml.md
@@ -5,7 +5,7 @@ weight: 1
 audience: pro
 ---
 
-DefectDojo Pro supports SAML authentication via the **Enterprise Settings** UI. Open-Source users should refer to the [Open-Source SAML guide](../OS__saml/).
+DefectDojo Pro supports SAML authentication via the **Enterprise Settings** UI. Open-Source users should refer to the [Open-Source SAML guide](/admin/sso/os__saml/).
 
 ## Setup
 
diff --git a/docs/content/admin/sso/_index.md b/docs/content/admin/sso/_index.md
@@ -20,15 +20,15 @@ aliases:
 
 Users can connect to DefectDojo with a Username and Password, but you can also allow users to authenticate via Single Sign-On (SSO). DefectDojo supports SAML and a range of OAuth providers:
 
-* **[Auth0](./PRO__auth0/)**
-* **[Azure Active Directory](./PRO__azure_ad/)**
-* **[GitHub Enterprise](./PRO__github_enterprise/)**
-* **[GitLab](./PRO__gitlab/)**
-* **[Google](./PRO__google/)**
-* **[KeyCloak](./PRO__keycloak/)**
-* **[Okta](./PRO__okta/)**
-* **[OIDC (OpenID Connect)](./PRO__oidc/)**
-* **[SAML](./PRO__saml/)**
+* **[Auth0](/admin/sso/pro__auth0/)**
+* **[Azure Active Directory](/admin/sso/pro__azure_ad/)**
+* **[GitHub Enterprise](/admin/sso/pro__github_enterprise/)**
+* **[GitLab](/admin/sso/pro__gitlab/)**
+* **[Google](/admin/sso/pro__google/)**
+* **[KeyCloak](/admin/sso/pro__keycloak/)**
+* **[Okta](/admin/sso/pro__okta/)**
+* **[OIDC (OpenID Connect)](/admin/sso/pro__oidc/)**
+* **[SAML](/admin/sso/pro__saml/)**
 
 SSO configuration can only be performed by a **Superuser**.
 
diff --git a/docs/content/asset_modelling/hierarchy/OS__sla_configuration.md b/docs/content/asset_modelling/hierarchy/OS__sla_configuration.md
@@ -73,6 +73,6 @@ Once a new SLA has been selected for a Product, all of the associated Findings'
 
 ## Notes on SLAs
 
-* SLAs can be optionally restarted once a [Risk Accepted](/triage_findings/findings_workflows/risk_acceptances/) Finding reactivates.  This is set when creating the Risk Acceptance by setting the **Restart SLA Expired** field.
+* SLAs can be optionally restarted once a [Risk Accepted](/triage_findings/findings_workflows/os__risk_acceptance/) Finding reactivates.  This is set when creating the Risk Acceptance by setting the **Restart SLA Expired** field.
 * Reimporting a Finding does not restart the SLA - SLAs are always calculated from when a Finding was first detected unless **Restart SLA on Finding Reactivation** is enabled.
 * Risk Acceptance expiry or reactivation of a Closed Finding are the only ways to reset or recalculate an SLA for a Finding once it is created (without changing the Product's SLA configuration).
diff --git a/docs/content/asset_modelling/hierarchy/PRO__priority_sla.md b/docs/content/asset_modelling/hierarchy/PRO__priority_sla.md
@@ -262,6 +262,6 @@ Once a new SLA has been selected for a Product, all of the associated Findings'
 
 ## Notes on SLAs
 
-* SLAs can be optionally restarted once a [Risk Accepted](/triage_findings/findings_workflows/risk_acceptances/) Finding reactivates.  This is set when creating the Risk Acceptance by setting the **Restart SLA Expired** field.
+* SLAs can be optionally restarted once a [Risk Accepted](/triage_findings/findings_workflows/pro__risk_acceptance/) Finding reactivates.  This is set when creating the Risk Acceptance by setting the **Restart SLA Expired** field.
 * Reimporting a Finding does not restart the SLA - SLAs are always calculated from when a Finding was first detected unless **Restart SLA on Finding Reactivation** is enabled.
 * Risk Acceptance expiry or reactivation of a Closed Finding are the only ways to reset or recalculate an SLA for a Finding once it is created (without changing the Product's SLA configuration).
diff --git a/docs/content/get_started/common_use_cases/common_use_cases.md b/docs/content/get_started/common_use_cases/common_use_cases.md
@@ -100,13 +100,13 @@ Key Concerns for Kate's Cloud Service:
 
 #### Tagging Shared Services
 
-Because Kate's model contains many shared services that can impact other Products, the team [Tags](/asset_modelling/tags/tagging_objects/) their Products to indicate which cloud offerings rely on those services.  This allows any issues with shared services to be filtered across Products and reported to the relevant teams.  Each of these shared services are in a single Product Type that separates them from the main cloud offerings.
+Because Kate's model contains many shared services that can impact other Products, the team [Tags](/asset_modelling/tags/os__tagging_objects/) their Products to indicate which cloud offerings rely on those services.  This allows any issues with shared services to be filtered across Products and reported to the relevant teams.  Each of these shared services are in a single Product Type that separates them from the main cloud offerings.
 
 ![image](images/example_product_hierarchy_microservices.png)
 
 Because the company is rapidly growing and tech leads are changing frequently, Kate can use Tags to track which tech lead is currently responsible for each cloud product, avoiding the need for constant manual updates to their DefectDojo system. These tech lead associations are tracked by a service that’s external to DefectDojo and can govern the import pipelines or call the DefectDojo API.
 
-For more information on Tagging, see our guide to [Tags](/asset_modelling/tags/tagging_objects/).
+For more information on Tagging, see our guide to [Tags](/asset_modelling/tags/os__tagging_objects/).
 
 #### RBAC Model
 
diff --git a/docs/content/get_started/pro/pro_features.md b/docs/content/get_started/pro/pro_features.md
@@ -16,7 +16,7 @@ Here is a list of DefectDojo Pro’s many additional features, along with links
 ### Pro UI
 
 DefectDojo's UI has been reworked in DefectDojo Pro to be faster, more functional, fully customizable, and better at navigating through enterprise-level data volume.  It also includes a dark mode.  
-See our [Pro UI Guide](../ui_pro_vs_os) for more information.
+See our [Pro UI Guide](/get_started/about/ui_pro_vs_os/) for more information.
 
 ![image](images/enabling_deduplication_within_an_engagement_2.png)
 
@@ -41,7 +41,7 @@ See our [Rules Engine Guide](/automation/rules_engine/about) for more info.
 
 ### Pro Dashboards and Reporting
 
-Generate [instant reports and metrics](../ui_pro_vs_os/#new-dashboards) to share the security posture of your apps and repos, evaluate your security tools and analyze your team's performance in addressing security issues.
+Generate [instant reports and metrics](/get_started/about/ui_pro_vs_os/#new-dashboards) to share the security posture of your apps and repos, evaluate your security tools and analyze your team's performance in addressing security issues.
 
 The graphics on the landing page can be exported as SVG files, and the data used to create the graphics can also be exported as a table. 
 
diff --git a/docs/content/open_source/archived_docs/usage/features.md b/docs/content/open_source/archived_docs/usage/features.md
@@ -10,7 +10,7 @@ aliases:
 ## Tags
 
 In DefectDojo, tags are a first class citizen and are recognized as the facilitators
-of organization within each level of the [data model](../models). Tags are
+of organization within each level of the data model. Tags are
 ideal for grouping objects in a manner that can be filtered out into smaller, more
 digestible chunks.
 
diff --git a/docs/content/open_source/contributing/documentation.md b/docs/content/open_source/contributing/documentation.md
@@ -6,14 +6,39 @@ weight: 2
 aliases:
   - /en/open_source/contributing/documentation
 ---
-The documentation is built with [Hugo](https://gohugo.io/) and uses the theme [Docsy](https://www.docsy.dev).
-Static files for the webside are build with github actions and are publish in the gh-pages branch.
+The documentation is built with [Hugo](https://gohugo.io/) and uses a variation of the [Doks](https://getdoks.org/) theme.
+
+Static files for the website are built with Github actions and are published in the gh-pages branch.
 
 ## How to run a local preview
 
 1. [Install Hugo](https://gohugo.io/getting-started/installing/). Make sure you have installed the extended version with Sass/SCSS support. Please note there are various Linux packages available on [Hugo GitHub](https://github.com/gohugoio/hugo/releases)
 2. Install required theme using Node.js: `cd docs` and then `npm install`.
-3. To run the Docs local server, `cd docs` to switch to the docs folder, and start the hugo server by running `npm run dev`.  Hot reloading is supported - pages will automatically update with changes while the server is running.
+3. To run the Docs local server, `cd docs` to switch to the docs folder, and start the Hugo development server by running `npm run dev`.  Hot reloading is supported - pages will automatically update with changes while the server is running.
 4. Visit [http://localhost:1313](http://localhost:1313).
 
-DefectDojo Docs are built using a variation of the [Doks](https://getdoks.org/) theme.
+## Contribution guidelines
+
+At this stage, our documentation is largely maintained by the DefectDojo Pro team, but we still welcome contributions to docs from the community.
+
+* Note that our Search functionality uses an external index which points at **docs.defectdojo.com** - so you won't be able to use Search to find any pages that are in dev.  Instead, consult your local sitemap.xml file to find any new URLs you've created: `http://localhost:1313/sitemap.xml`
+* Our docs are currently written for two audiences: Open Source and Pro, so please include an appropriate label in your Hugo front matter, like so:
+
+```
+---
+title: "Your great article"
+audience: opensource
+---
+```
+
+* Do not use relative link paths: `[link](../your_article/)`.  Although technically 'legal' in Hugo, you will not pass our unit tests.
+
+## Unit tests for docs
+
+DefectDojo's docs use Lychee to check for 404s and other link errors.  To run this test locally, you can run this command from the root of the repo.  This will delete anything in Hugo's `/public/` folder and then rebuild.
+
+`cd docs && rm -rf public/ && hugo --minify --gc --config config/production/hugo.toml && lychee --offline --no-progress --root-dir public './public/**/*.html`
+
+### Theme overrides
+
+We use significant CSS overrides which are detailed in `docs/layouts`.
diff --git a/docs/content/releases/os_upgrading/2.2.md b/docs/content/releases/os_upgrading/2.2.md
@@ -8,5 +8,5 @@ exclude_search: true
 Upgrade to 2.0.0 contained migration of endpoints. Some parts of migration haven't been done properly. This deficiency
 may manifest as a doubled slash in endpoint URLs (like `http://foo.bar:8080//test`) or as a problem with deduplication
 of the same endpoints. The mentioned bug was fixed in 2.2.0 and if you have seen these kinds of problems, just rerun
-"Endpoint migration" as it is written in [Upgrading to DefectDojo Version 2.0.x.](/open_source/upgrading/2.0/#endpoints).
+"Endpoint migration" as it is written in [Upgrading to DefectDojo Version 2.0.x.](/releases/os_upgrading/2.0/#endpoints).
 
diff --git a/docs/content/releases/os_upgrading/2.52.md b/docs/content/releases/os_upgrading/2.52.md
@@ -48,7 +48,7 @@ If you want to be 110% sure no tasks will be lost you could perform the upgrade
 
 `docker compose down`
 
-4) Continue the upgrade as normal per the [upgrade guide](upgrading_guide)
+4) Continue the upgrade as normal per the [upgrade guide](/releases/os_upgrading/upgrading_guide/)
 `docker compose pull`
 `docker compose up -d`
 
diff --git a/docs/content/releases/pro/changelog.md b/docs/content/releases/pro/changelog.md
@@ -8,7 +8,7 @@ aliases:
 
 Here are the release notes for **DefectDojo Pro (Cloud Version)**. These release notes are focused on UX, so will not include all code changes.
 
-For Open Source release notes, please see the [Releases page on GitHub](https://github.com/DefectDojo/django-DefectDojo/releases), or alternatively consult the Open Source [upgrade notes](/changelog/os_upgrading/upgrading_guide/).
+For Open Source release notes, please see the [Releases page on GitHub](https://github.com/DefectDojo/django-DefectDojo/releases), or alternatively consult the Open Source [upgrade notes](/releases/os_upgrading/upgrading_guide/).
 
 ## Feb 2026: v2.55
 
@@ -633,7 +633,7 @@ configuration fields.
 - **(API)**  It is now possible to prefetch a Finding with attached files via API.
 - **(Login)**  A new "Forgot Username" link has been added to the login form.  The link will navigate to a page which requests the user's email address. The username will be sent to that address if it exists.
 - **Risk Acceptances**  Notes are now added to Findings when they are removed from Risk Acceptances.
-- **(Risk Acceptance)**  Risk Acceptance overhaul. Feature has been extended with new functions.  See [Risk Acceptance documentation](/triage_findings/findings_workflows/risk_acceptances/) for more details.
+- **(Risk Acceptance)**  Risk Acceptance overhaul. Feature has been extended with new functions.  See [Risk Acceptance documentation](/triage_findings/findings_workflows/pro__risk_acceptance/) for more details.
 - **Tools**  Qualys HackerGuardian parser added.
 - **Tools**  Semgrep Parser updated with new severity mappings. HackerOne parser updated and now supports bug bounty reports.
 - **Tools**  fixed an issue where certain tools would not process asyncronously: Whitehat_Sentinel, SSLyze, SSLscan, Qualys_Webapp, Mend, Intsights, H1, and Blackduck.
diff --git a/docs/content/triage_findings/findings_workflows/finding_status_definitions.md b/docs/content/triage_findings/findings_workflows/finding_status_definitions.md
