Added link checker by mnocon · Pull Request #3153 · ibexa/documentation-developer

mnocon · 2026-04-21T07:35:07Z

This PR makes it possible to check links in the documentation

Problem, constraints, and assumptions:

Broken links in the doc = bad
we only care about checking the external links: MkDocs is doing a great job of checking all internal links within a project, including fragments
doc.ibexa.co is protected by Cloudflare, which blocks all requests coming from IPs related to GitHub Actions
- this means that it's not possible to verify links to doc.ibexa.co on CI environment

Tool used

Lychee is used: https://lychee.cli.rs/

It's fast
Has a lot of configuration options (including ignoring certain links, remapping URLS (crucial), redirections, checking fragments and text fragments)
Has good CI integration
Full run locally takes about ~10 minutes

How it works

Ignoring files

.lycheeignore is used for URLs that cannot be checked easily

Because links to doc.ibexa.co cannot be checked on CI (crawlers are blocked), and checking them is the main point, another solution is used: link remapping.

Links leading to doc.ibexa.co are remapped to local instances of the doc:

dev doc 5.0 (by default uses 5.0 branch)
dev doc 4.6 (by default uses 4.6 branch)
user doc 5.0 (by default uses 5.0 branch)
user doc 4.6 (by default uses 4.6 branch)
connect main (by default uses main branch)

I've checked links to lower versions of the doc (which cannot be checked on CI) manually, fixed them, and then added to the .lycheeignore file.

The branches can be overwritten when triggering the job from CI

The idea is that we can use the release_4.6.x branches, to make sure all the links are correct before the release

Fixing the links

The rest of the PR fixes existing links:

redirects are updated to use the new location
broken links are fixed or removed, if removing is not possible

This PR is split into 2 commits:

adding the tool: deb36e3
fixing the links: ac2a7a4

The job with broken links is here:
https://github.com/ibexa/documentation-developer/actions/runs/26101343148/job/76752887924

404 - external link broken
30x - redirects
Cannot find file: File not found - documentation link broken

github-actions · 2026-04-21T07:35:21Z

Preview of modified files

Preview of modified Markdown:

mnocon · 2026-05-19T18:28:52Z

 - Rewrite custom web front end to use the new Platform/Symfony stack, see [Beginner Tutorial](beginner_tutorial.md)
 - Rewrite custom admin modules to use the new Platform/Symfony stack
-    - And if you do this while on 5.x, you can use several of the [available legacy migration features](https://doc.ez.no/display/EZP/Legacy+code+and+features) to make the new code appear in legacy admin
+    - And if you do this while on 5.x, you can use several of the [available legacy migration features](https://web.archive.org/web/20140911035812/https://doc.ez.no/display/EZP/Legacy+code+and+features) to make the new code appear in legacy admin


These pages are no longer online, I feel linking to their archived versions is the right thing to do - in case someone is stuck on a legacy version

mnocon · 2026-05-19T18:35:25Z


 Also, you can now apply new filters that are intended to help you declutter the calendar view.

-For more information, see [Calendar widget](https://doc.ibexa.co/projects/userguide/en/latest/publishing/advanced_publishing_options/#calendar-widget).


This page is broken, no sense of ressurecting it right now

If it's in 3.2 and https://doc.ibexa.co/projects/userguide/en/3.3/publishing/advanced_publishing_options/#calendar-widget is still there, that could be the fix.

Thanks, added that in the latest commit

sonarqubecloud · 2026-05-19T18:51:33Z

Quality Gate failed

Failed conditions
1 Security Hotspot

See analysis details on SonarQube Cloud

adriendupuis · 2026-06-30T11:54:32Z

+    # userguide en/latest/ — map to the newest available clone (userdoc-5.0)
+    "https://doc\\.ibexa\\.co/projects/userguide/en/latest/([^#]+\\.html)(#.*)?$ file://__BASE_DIR__/repositories/userdoc-5.0/site/$1$2",
+    "https://doc\\.ibexa\\.co/projects/userguide/en/latest/([^#/]+(?:/[^#/]+)*)/?(#.*)?$ file://__BASE_DIR__/repositories/userdoc-5.0/site/$1/index.html$2",
+    "https://doc\\.ibexa\\.co/projects/userguide/en/latest/$ file://__BASE_DIR__/repositories/userdoc-5.0/site/index.html",


I think we should fail on latest. We should always use 5.0. latest will be 6.0 one day, and having 5.0 targeting 6.0 will be wrong. And maybe we already have 4.6 targeting 5.0 issues.
userguide/en/latest → userdoc-5.0 remapping shouldn't be needed and we shouldn't have to maintain this block on 6.0 release.

Nice, like the idea! Will implement

Looking at this, there are some legitimate use cases for latest in the doc, so I've kept the rule - but I've reviewed every "latest" link and replaced it with a specific version call where applicable.

This is done in github.com//pull/3153/changes/9ea1af8df480c1cd628c2adf882fe715c04db0b9

Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>

+
+            - name: Comment broken links
+              if: github.event_name == 'pull_request'
+              uses: marocchino/sticky-pull-request-comment@v2


mnocon · 2026-07-02T09:53:21Z

+                      lychee-
+
+            - name: Check links
+              uses: lycheeverse/lychee-action@master


This is temporary, to use 0.24.2.

Will change this to a released version once github.com/lycheeverse/lychee-action/issues/332 is fixed

github-actions · 2026-07-02T10:02:11Z

Summary

Status	Count
🔍 Total	758306
🔗 Unique	14999
✅ Successful	7260
⏳ Timeouts	0
🔀 Redirected	1
👻 Excluded	751042
❓ Unknown	0
🚫 Errors	4
⛔ Unsupported	0

Errors per input

Errors in site/api/rest_api/rest_api_authentication/index.html

[502] https://oauth.net/2/ (at 14796:39) | Rejected status code: 502 Bad Gateway

Errors in site/api/rest_api/rest_api_usage/rest_api_usage/index.html

[403] https://www.iso.org/glossary-for-iso-3166.html (at 14379:34) | Rejected status code: 403 Forbidden

Errors in site/content_management/field_types/field_type_reference/countryfield/index.html

[403] https://www.iso.org/iso-3166-country-codes.html (at 14337:119) | Rejected status code: 403 Forbidden

Errors in site/users/oauth_server/index.html

[502] https://oauth.net/2/scope/ (at 14454:49) | Rejected status code: 502 Bad Gateway

Redirects per input

Redirects in site/search/search_engines/solr_search_engine/install_solr/index.html

https://cwiki.apache.org/confluence/display/solr/CoreAdmin --[302]--> https://cwiki.apache.org/confluence/spaces/SOLR/pages/120722785/CoreAdmin

Full Github Actions output

adriendupuis · 2026-07-02T12:38:51Z

+# AI provider consoles — redirect to login pages (302/307)
+https://aistudio\.google\.com/app/api-keys
+https://console\.anthropic\.com/login
+https://docs\.claude\.com/en/docs/about-claude/models/overview


Please, remove https://docs\.claude\.com/en/docs/about-claude/models/overview

The redirection chain is
302 https://docs.claude.com/en/docs/about-claude/models/overview → 200 https://platform.claude.com/docs/en/about-claude/models/overview

It's to be fixed in docs/ai/ai_actions/configure_ai_actions.md line 73

Notice that line 96 this redirection was fixed:
302 https://docs.anthropic.com/en/docs/about-claude/models/overview → 200 https://platform.claude.com/docs/en/about-claude/models/overview
Two different URLs where used to target the same content? Or two different pages were merged?

Suggested change

https://docs\.claude\.com/en/docs/about-claude/models/overview

Done in 44be7e1

adriendupuis · 2026-07-02T12:45:46Z

+^https://support\.ibexa\.co/
+^https://redocly\.com/redoc/
+^https://updates\.ibexa\.co
+^https://console\.cloud\.google\.com


Please, group with https://aistudio\.google\.com/app/api-keys
Both are the same chain of redirections to https://accounts.google.com/v3/signin

Done in 44be7e1

mnocon force-pushed the link-checker branch from fa3e663 to cef4f06 Compare April 21, 2026 10:33

mnocon force-pushed the link-checker branch 4 times, most recently from 21146e4 to deb36e3 Compare May 19, 2026 13:45

mnocon commented May 19, 2026

View reviewed changes

mnocon marked this pull request as ready for review June 23, 2026 08:24

mnocon force-pushed the link-checker branch from e6ffc02 to 0f88f0d Compare June 23, 2026 10:34

github-advanced-security AI found potential problems Jun 23, 2026

View reviewed changes

Comment thread .github/workflows/link_check.yaml Fixed

mnocon force-pushed the link-checker branch 2 times, most recently from d7aae42 to 15d6488 Compare June 23, 2026 15:43

github-advanced-security AI found potential problems Jun 23, 2026

View reviewed changes

Comment thread .github/workflows/link_check.yaml Fixed

mnocon force-pushed the link-checker branch 2 times, most recently from c20b64d to 659f9c9 Compare June 24, 2026 09:29

mnocon added the Needs DOC review label Jun 29, 2026

mnocon requested a review from a team June 29, 2026 13:42

ibexa-workflow-automation-1 Bot requested review from adriendupuis, dabrt and julitafalcondusza and removed request for a team June 29, 2026 13:42

adriendupuis reviewed Jun 30, 2026

View reviewed changes

Comment thread lychee.toml.dist

adriendupuis reviewed Jun 30, 2026

View reviewed changes

Comment thread .github/workflows/link_check.yaml

mnocon force-pushed the link-checker branch from a8c22bd to 024b9ff Compare July 2, 2026 08:36

mnocon added 3 commits July 2, 2026 10:37

Added link checking

ed8b9ac

Fixed links

cf71662

Empty commit

1d9f7be

mnocon and others added 6 commits July 2, 2026 10:38

Fixed remaining main -> 5.0 link

e517016

Avoid parallelism issues

3fa0cd3

Fixed SymfonyCasts links

6bef33a

Brought back removed Calendar widget link

6ec5a7c

Apply suggestions from code review

6db1546

Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>

Review existing "latest" links

9ea1af8

mnocon force-pushed the link-checker branch 2 times, most recently from 57c9824 to 9b162d2 Compare July 2, 2026 08:54

github-advanced-security AI found potential problems Jul 2, 2026

View reviewed changes

Comment thread .github/workflows/link_check.yaml

- name: Comment broken links

if: github.event_name == 'pull_request'

uses: marocchino/sticky-pull-request-comment@v2

mnocon force-pushed the link-checker branch 2 times, most recently from 4ada727 to aa9c769 Compare July 2, 2026 09:21

github-advanced-security AI found potential problems Jul 2, 2026

View reviewed changes

Bumped lychee, add comment

f3fb8b1

mnocon force-pushed the link-checker branch from aa9c769 to f3fb8b1 Compare July 2, 2026 09:51

Increased cache age

43fc300

mnocon requested a review from adriendupuis July 2, 2026 10:03

adriendupuis requested changes Jul 2, 2026

View reviewed changes

mnocon and others added 5 commits July 2, 2026 15:43

Removed artifact step, fixed comment step

e550a92

Increased verbosity

edcc6a2

Review feedback

44be7e1

Check jobSummary: true

36c0b4b

modelcontextprotocol.io/…/latest→…/2025-11-25

bc5e060

mnocon requested a review from adriendupuis July 3, 2026 11:06

Group Google. Update Claude

d8b459f

adriendupuis approved these changes Jul 3, 2026

View reviewed changes

mnocon merged commit 70a02db into 5.0 Jul 3, 2026
9 of 11 checks passed

mnocon deleted the link-checker branch July 3, 2026 12:09

mnocon mentioned this pull request Jul 3, 2026

Added link checker ibexa/documentation-user#412

Draft


		Also, you can now apply new filters that are intended to help you declutter the calendar view.

		For more information, see [Calendar widget](https://doc.ibexa.co/projects/userguide/en/latest/publishing/advanced_publishing_options/#calendar-widget).

Uh oh!

Conversation

mnocon commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem, constraints, and assumptions:

Tool used

How it works

Fixing the links

Uh oh!

github-actions Bot commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview of modified files

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented May 19, 2026

Quality Gate failed

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Errors per input

Errors in site/api/rest_api/rest_api_authentication/index.html

Errors in site/api/rest_api/rest_api_usage/rest_api_usage/index.html

Errors in site/content_management/field_types/field_type_reference/countryfield/index.html

Errors in site/users/oauth_server/index.html

Redirects per input

Redirects in site/search/search_engines/solr_search_engine/install_solr/index.html

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mnocon commented Apr 21, 2026 •

edited

Loading

github-actions Bot commented Apr 21, 2026 •

edited

Loading

github-actions Bot commented Jul 2, 2026 •

edited

Loading