Fix URLs and expand Lychee coverage (#14855)

* fix: correct URL for 'Model Your Assets' in menu configuration

* ci(docs): expand lychee to catch absURL nav links and in-app help links

Add `--remap` so absolute `docs.defectdojo.com` URLs resolve against the
freshly built site. Previously these were skipped as remote URLs in
offline mode, which masked the broken Model Your Assets menu link fixed
in #14855 — Hugo renders menu items with `absURL`, so a broken nav URL
hides in `https://docs.defectdojo.com/...` form and lychee excludes it.

Add a second lychee invocation that scans every file under `dojo/` that
hardcodes a `docs.defectdojo.com` URL (Django templates, settings) and
checks those against the same built site, so an in-app help link to a
moved or renamed doc page fails CI instead of silently 404ing in the UI.

Update the contributing docs with the local-reproduction commands.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: fix five 404 links surfaced by expanded lychee check

The new --remap flag added in the previous commit causes lychee to
resolve absolute docs.defectdojo.com URLs against the built site. Five
in-content links to moved/renamed pages, previously masked because they
were skipped as remote URLs in --offline mode, now fail. Repoint each
to its current canonical path.

- get_started/about/about_defectdojo.md: architecture and running-in-
  production now live under /get_started/open_source/, not
  /open_source/installation/.
- metrics_reports/reports/using_the_report_builder.md: working_with_
  generated_reports uses underscores, not hyphens, and is under
  /metrics_reports/reports/ canonically.
- supported_tools/parsers/file/aws_prowler_v3plus.md and burp_suite_dast.md:
  parser pages live under /supported_tools/parsers/file/, not
  /supported_tools/file/.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Paul Osinski <posinski34@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

.github/workflows/validate_docs_build.yml

@@ -44,6 +44,36 @@ jobs:
       - name: Check internal links
         uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2
         with:
-          args: --offline --no-progress --root-dir docs/public './docs/public/**/*.html'
+          # --remap makes lychee resolve absolute docs.defectdojo.com URLs against
+          # the freshly built site, so absURL-rendered links (e.g. nav menu items)
+          # are verified as 404s instead of being skipped as remote URLs.
+          args: >-
+            --offline --no-progress
+            --root-dir ${{ github.workspace }}/docs/public
+            --remap "https://docs.defectdojo.com file://${{ github.workspace }}/docs/public"
+            './docs/public/**/*.html'
           fail: true
 
+      - name: Check in-app docs help links
+        # Find every file under dojo/ that hardcodes a docs.defectdojo.com URL
+        # (templates, settings, etc.) and check those links against the freshly
+        # built site. --remap turns the absolute docs URLs into local file lookups;
+        # --exclude '%7[BD]' drops URL-encoded Django template tags ({% ... %})
+        # so only real external docs URLs are checked. lychee is on $PATH from
+        # the previous lychee-action step.
+        run: |
+          set -euo pipefail
+          mapfile -t files < <(grep -rl 'docs\.defectdojo\.com' dojo/ \
+            --include='*.html' --include='*.py' --include='*.tpl')
+          if [ "${#files[@]}" -eq 0 ]; then
+            echo "No files reference docs.defectdojo.com — pattern is stale." >&2
+            exit 1
+          fi
+          printf 'Checking in-app docs links in:\n'
+          printf '  %s\n' "${files[@]}"
+          lychee --offline --no-progress \
+            --root-dir "${GITHUB_WORKSPACE}/docs/public" \
+            --remap "https://docs.defectdojo.com file://${GITHUB_WORKSPACE}/docs/public" \
+            --exclude '%7[BD]' \
+            "${files[@]}"
+

docs/config/_default/menus/menus.en.toml

@@ -15,7 +15,7 @@
 
 [[main]]
   name = "Model Your Assets"
-  url = "/asset_modelling/hierarchy/pro__assets_organizations/"
+  url = "/asset_modelling/pro_hierarchy/assets_organizations/"
   weight = 13
 
 [[main]]

docs/content/get_started/about/about_defectdojo.md

@@ -68,8 +68,8 @@ For teams managing a smaller volume of Findings, DefectDojo Open-Source is a gre
 There are a few supported ways to install DefectDojo’s Open-Source edition ([available on Github](https://github.com/DefectDojo/django-DefectDojo)):
 
 [Docker Compose](https://github.com/DefectDojo/django-DefectDojo/blob/master/readme-docs/DOCKER.md) is the easiest method to install the core program and services required to run DefectDojo.
-Our [Architecture](https://docs.defectdojo.com/open_source/installation/architecture/) guide gives you an overview of each service and component used by DefectDojo.
-[Running In Production](https://docs.defectdojo.com/open_source/installation/running-in-production/) lists system requirements, performance tweaks and maintenance processes for running DefectDojo on a production server (with Docker Compose).
+Our [Architecture](https://docs.defectdojo.com/get_started/open_source/architecture/) guide gives you an overview of each service and component used by DefectDojo.
+[Running In Production](https://docs.defectdojo.com/get_started/open_source/running-in-production/) lists system requirements, performance tweaks and maintenance processes for running DefectDojo on a production server (with Docker Compose).
 
 Kubernetes is not fully supported at the Open-Source level, but this guide can be referenced and used as a starting point to integrate DefectDojo into Kubernetes architecture.
 

docs/content/get_started/contributing/documentation.md

@@ -37,9 +37,22 @@ audience: opensource
 
 ## 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.
+DefectDojo's docs use Lychee to check for 404s and other link errors.  CI runs two checks: the rendered docs site, and any `docs.defectdojo.com` URLs hardcoded into the Django app (templates and settings).  Both use a `--remap` so absolute `docs.defectdojo.com` URLs resolve against the freshly built site.  To run both locally from the root of the repo:
 
-`cd docs && rm -rf public/ && hugo --minify --gc --config config/production/hugo.toml && lychee --offline --no-progress --root-dir public './public/**/*.html'`
+```
+cd docs && rm -rf public/ && hugo --minify --gc --config config/production/hugo.toml && cd ..
+
+lychee --offline --no-progress \
+  --root-dir "$PWD/docs/public" \
+  --remap "https://docs.defectdojo.com file://$PWD/docs/public" \
+  './docs/public/**/*.html'
+
+lychee --offline --no-progress \
+  --root-dir "$PWD/docs/public" \
+  --remap "https://docs.defectdojo.com file://$PWD/docs/public" \
+  --exclude '%7[BD]' \
+  $(grep -rl 'docs\.defectdojo\.com' dojo/ --include='*.html' --include='*.py' --include='*.tpl')
+```
 
 ### Theme overrides
 

docs/content/metrics_reports/reports/using_the_report_builder.md

@@ -5,7 +5,7 @@ weight: 1
 aliases:
   - /en/share_your_findings/pro_reports/using_the_report_builder
 ---
-DefectDojo allows you to create Custom Reports for external audiences, which summarize the Findings or Endpoints that you wish to report on. Custom Reports can include branding and boilerplate text, and can also be used as **[Templates](https://docs.defectdojo.com/en/pro_reports/working-with-generated-reports/)** for future reports.
+DefectDojo allows you to create Custom Reports for external audiences, which summarize the Findings or Endpoints that you wish to report on. Custom Reports can include branding and boilerplate text, and can also be used as **[Templates](https://docs.defectdojo.com/metrics_reports/reports/working_with_generated_reports/)** for future reports.
 
 ## Opening the Report Builder
 

docs/content/supported_tools/parsers/file/aws_prowler_v3plus.md

@@ -5,7 +5,7 @@ toc_hide: true
 
 ### File Types
 DefectDojo parser accepts a native `json` file produced by prowler v3 with file extension `.json` or a `ocsf-json` file produced by prowler v4 with file extension `.ocsf.json`. 
-Please note: earlier versions of AWS Prowler create output data in a different format. See our other [prowler parser documentation](https://docs.defectdojo.com/supported_tools/file/aws_prowler/) if you are using an earlier version of AWS Prowler. 
+Please note: earlier versions of AWS Prowler create output data in a different format. See our other [prowler parser documentation](https://docs.defectdojo.com/supported_tools/parsers/file/aws_prowler/) if you are using an earlier version of AWS Prowler. 
 
 JSON reports can be created from the [AWS Prowler v3 CLI](https://docs.prowler.com/projects/prowler-open-source/en/v3/tutorials/reporting/#json) using the following command: `prowler <provider> -M json`
 

docs/content/supported_tools/parsers/file/burp_suite_dast.md

@@ -7,7 +7,7 @@ toc_hide: true
 The Burp Suite DAST Scan parser processes HTML reports from Burp Suite DAST and imports the findings into DefectDojo. The parser extracts vulnerability details, severity ratings, descriptions, remediation steps, and other metadata from the HTML report.
 
 ## Supported File Types
-The parser accepts a Standard Report as an HTML file. To parse an XML file instead, use the [Burp XML parser](https://docs.defectdojo.com/supported_tools/file/burp/).
+The parser accepts a Standard Report as an HTML file. To parse an XML file instead, use the [Burp XML parser](https://docs.defectdojo.com/supported_tools/parsers/file/burp/).
 
 See the Burp documentation for information on how to export a Standard Report: [Burp Suite DAST Downloading reports](https://portswigger.net/burp/documentation/dast/user-guide/work-with-scan-results/generate-reports)