Run MKDocs strict validation on new commit pushes. by lrcouto · Pull Request #5173 · kedro-org/kedro

lrcouto · 2025-10-21T02:49:48Z

Description

We want to run stricter validation on MKDocs to prevent broken links and anchors.

This PR introduces a new CI job that builds MKDocs with the --strict flag to check for broken links and anchors. It also changes MKDocs configuration adding:

validation:
  omitted_files: warn
  absolute_links: warn
  unrecognized_links: warn
  anchors: warn

So all of those things throw warnings, and will cause the CI to fail.

Finally, several broken internal links and other warnings thrown by mkdocs build --strict have been fixed.

Development notes

Developer Certificate of Origin

We need all contributions to comply with the Developer Certificate of Origin (DCO). All commits must be signed off by including a Signed-off-by line in the commit message. See our wiki for guidance.

If your PR is blocked due to unsigned commits, then you must follow the instructions under "Rebase the branch" on the GitHub Checks page for your PR. This will retroactively add the sign-off to all unsigned commits and allow the DCO check to pass.

Checklist

Read the contributing guidelines
Signed off each commit with a Developer Certificate of Origin (DCO)
Opened this PR as a 'Draft Pull Request' if it is work-in-progress
Updated the documentation to reflect the code changes
Added a description of this change in the RELEASE.md file
Added tests to cover my changes
Checked if this change will affect Kedro-Viz, and if so, communicated that with the Viz team

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

.github/workflows/docs-linkcheck.yml

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

lrcouto · 2025-10-23T00:04:43Z

Language linter started failing after I fixed the broken anchors because apparently the word "alternatively" (which was there before) is "too wordy". I'm electing to ignore that. =p

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

rashidakanchwala

Thanks Laura!

merelcht

The setup looks good! I left some comments for the links. Let's try still make them point to specific sections where possible.

merelcht · 2025-10-23T12:14:24Z

.github/workflows/docs-linkcheck.yml

+
+    strategy:
+      matrix:
+        python-version: [ "3.10", "3.11", "3.12", "3.13" ]


No need to run this for every python version. Let's just do the same as for the lint jobs: 3.11

merelcht · 2025-10-23T12:16:33Z

docs/build/run_a_pipeline.md

 ## Configure `kedro run` arguments

-The [Kedro CLI documentation](../getting-started/commands_reference.md#run-the-project) lists the available CLI options for `kedro run`. You can alternatively supply a configuration file that contains the arguments to `kedro run`.
+The [Kedro CLI documentation](../getting-started/commands_reference.md) lists the available CLI options for `kedro run`. You can alternatively supply a configuration file that contains the arguments to `kedro run`.


Could this link to https://docs.kedro.org/en/1.0.0/getting-started/commands_reference/#kedro-run ?

merelcht · 2025-10-23T12:18:09Z

docs/configure/configuration_basics.md


 ### How to change the configuration source folder at runtime
-Specify a source folder for the configuration files at runtime using the [`kedro run` CLI command](../getting-started/commands_reference.md#modifying-a-kedro-run) with the `--conf-source` flag as follows:
+Specify a source folder for the configuration files at runtime using the [`kedro run` CLI command](../getting-started/commands_reference.md#kedro-commands) with the `--conf-source` flag as follows:


I think this should also link to : https://docs.kedro.org/en/1.0.0/getting-started/commands_reference/#kedro-run

merelcht · 2025-10-23T12:18:40Z

docs/deploy/single_machine.md


 ## Package-based
-If you prefer not to use containerisation, you can instead package your Kedro project using [`kedro package`](../getting-started/commands_reference.md#deploy-the-project).
+If you prefer not to use containerisation, you can instead package your Kedro project using [`kedro package`](../getting-started/commands_reference.md#kedro-commands).


https://docs.kedro.org/en/1.0.0/getting-started/commands_reference/#kedro-package

merelcht · 2025-10-23T12:19:48Z

docs/getting-started/faq.md

 * [How do I specify additional configuration environments](../configure/configuration_basics.md#how-to-specify-additional-configuration-environments)?
 * [How do I change the default overriding configuration environment](../configure/configuration_basics.md#how-to-change-the-default-overriding-environment)?
 * [How do I use only one configuration environment](../configure/configuration_basics.md#how-to-use-only-one-configuration-environment)?
-* [How do I use Kedro without the rich library](../configure/configuration_basics.md#how-to-use-kedro-without-the-rich-library)?


I think this just moved to https://docs.kedro.org/en/1.0.0/develop/logging/#how-to-use-logging-without-the-rich-library

I saw this one, but I thought it'd be weird to put a link from the logging section in there when all of the other links are from the configuration section. Do you think it'd still be relevant?

I think it's still a good link to have on the getting started FAQ. It might be harder to find for people otherwise.

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

merelcht

LGTM! 👍

docs/build/slice_a_pipeline.md

docs/tutorials/add_another_pipeline.md

Co-authored-by: Merel Theisen <49397448+merelcht@users.noreply.github.com> Signed-off-by: L. R. Couto <57910428+lrcouto@users.noreply.github.com>

Add linkcheck job to github CI

c6caf4c

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

github-advanced-security bot found potential problems Oct 21, 2025

View reviewed changes

.github/workflows/docs-linkcheck.yml Fixed Show fixed Hide fixed

Add permissions

1ab0d44

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

lrcouto marked this pull request as ready for review October 21, 2025 03:28

lrcouto requested a review from merelcht as a code owner October 21, 2025 03:28

lrcouto marked this pull request as draft October 21, 2025 03:29

lrcouto and others added 9 commits October 21, 2025 00:48

Run on all pushes

ee84fad

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

Edit the correct file

5c453fb

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

Install UV the same way we do on unit tests

5c389c1

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

Merge branch 'main' into linkcheck-mkdocs

2f68f7b

Fix MKdocs warnings

c903f91

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

Lint

700410a

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

Add Lychee to github CI job

f1d23e6

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

Install lychee with cargo

72d6f1c

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

Add stricter validation to docs, fix broken anchors

6f87916

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

Remove lychee from CI

94ae652

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

lrcouto changed the title ~~Add linkcheck job to github CI~~ Run MKDocs strict validation on new commit pushes. Oct 23, 2025

lrcouto marked this pull request as ready for review October 23, 2025 03:16

lrcouto requested a review from yetudada as a code owner October 23, 2025 03:16

lrcouto requested review from rashidakanchwala and ravi-kumar-pilla October 23, 2025 03:17

lrcouto mentioned this pull request Oct 23, 2025

[Docs] Kedro docs should validate internal links and build --strict #5159

Closed

rashidakanchwala approved these changes Oct 23, 2025

View reviewed changes

merelcht reviewed Oct 23, 2025

View reviewed changes

Make anchor links more specific, run lincheck only on python 3.11

2604c88

Signed-off-by: Laura Couto <laurarccouto@gmail.com>

lrcouto mentioned this pull request Oct 24, 2025

Fix broken documentation links after migration to MkDocs #5171

Closed

merelcht approved these changes Oct 24, 2025

View reviewed changes

docs/build/slice_a_pipeline.md Outdated Show resolved Hide resolved

docs/tutorials/add_another_pipeline.md Outdated Show resolved Hide resolved

lrcouto and others added 2 commits October 24, 2025 13:12

Update docs/build/slice_a_pipeline.md

be1e8e5

Co-authored-by: Merel Theisen <49397448+merelcht@users.noreply.github.com> Signed-off-by: L. R. Couto <57910428+lrcouto@users.noreply.github.com>

Update docs/tutorials/add_another_pipeline.md

82fe313

Co-authored-by: Merel Theisen <49397448+merelcht@users.noreply.github.com> Signed-off-by: L. R. Couto <57910428+lrcouto@users.noreply.github.com>

lrcouto merged commit 6a94c02 into main Oct 24, 2025
37 of 38 checks passed

lrcouto deleted the linkcheck-mkdocs branch October 24, 2025 13:38

Conversation

lrcouto commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Development notes

Developer Certificate of Origin

Checklist

Uh oh!

Uh oh!

lrcouto commented Oct 23, 2025

Uh oh!

rashidakanchwala left a comment

Choose a reason for hiding this comment

Uh oh!

merelcht left a comment

Choose a reason for hiding this comment

Uh oh!

merelcht Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

merelcht Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

merelcht Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

merelcht Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

merelcht Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

lrcouto Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

merelcht Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

merelcht left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lrcouto commented Oct 21, 2025 •

edited

Loading