feat: add markdown link checking #1713
Conversation
This set of changes adds two Makefile targets * markdown-link-check-install: installs the markdown-link-check tool which is able to check whether links are alive * lint/markdown-link-check: Runs markdown-link-check checking all .md (markdown) files in the project. The bin directory is excluded markdown-link-check is able to check: * URLs * Relative links to other files in the projects * `mailto:` links Additionally, a markdown-link-check configuration file `.markdown-link-check/markdown-link-check-config.json` relative to the project's root has been added. This file can be used when running the markdown-link-check tool with the `-c` flag referencing it. The `lint/markdown-link-check` Makefile target makes use of it automatically. Some URL patterns have been configured to be ignored in the markdown-link-check configuration file. This URL patterns correspond to URLs that resolve to private IP addresses or that are private GitHub/GitLab repositories.
github-actions
bot
added
common
documentation
| @@ -0,0 +1,38 @@ | |||
| name: PR check Markdown links | |||
There was a problem hiding this comment.
Separating this into its own workflow is intentional. The reason for it is that we want to take advantage of parallelism and restrict the set of events that are considered.
The same applies to the workflow for the periodic execution
| use-quiet-mode: 'no' | ||
| use-verbose-mode: 'yes' | ||
| config-file: './.markdown-link-check/markdown-link-check-config.json' | ||
| check-modified-files-only: 'no' |
There was a problem hiding this comment.
This is intentional:
All the specified md files and directories in the workflows are
intentionally checked, independently on whether they have been
modified or not. The reason for this is that even if a given .md
file has not been modified, its links can become broken. For example,
if a PR moves .md files from directories and some other .md files
contain relative links referencing the old path of the moved files,
then the links become broken even though the file containing the
references not being modified.
| @@ -263,6 +280,10 @@ lint/templates: specinstall | |||
| $(SPECTRAL) lint templates/*.yml templates/*.yaml --ignore-unknown-format --ruleset .validate-templates.yaml | |||
| .PHONY: lint/templates | |||
|
|
|||
| MARKDOWN_LINK_CHECK_CONFIG_DIR ?= $(PROJECT_PATH)/.markdown-link-check | |||
| MARKDOWN_LINK_CHECK_CONFIG ?= $(MARKDOWN_LINK_CHECK_CONFIG_DIR)/markdown-link-check-config.json | |||
| lint/markdown-link-check: markdown-link-check-install | |||
There was a problem hiding this comment.
This hasn't been added to the lint task intentionally. As it might be time consuming I kept it separate from there.
What's the motivation for running the check on a weekly basis on top of having the check run on every PR? I presume it is to detect any broken external link? |
Correct. A link reference to a URL can become broken even if no PRs are opened. |
Two GitHub workflows have been added that perform Markdown links checking: * .github/workflows/markdown-link-check-pr.yaml: Executed in each PR. * .github/workflos/markdown-link-check-weekly.yaml: Executed Weekly on Mondays at 07:00 UTC. All the specified md files and directories in the workflows are intentionally checked, independently on whether they have been modified or not. The reason for this is that even if a given .md file has not been modified, its links can become broken. For example, if a PR moves .md files from directories and some other .md files contain relative links referencing the old path of the moved files, then the links become broken even though the file containing the references not being modified.
miguelsorianod
force-pushed
the
add-markdown-link-checking
branch
from
7c8b7c6
to
a0c6b4c
Compare
Codecov Report
Additional details and impacted files@@ Coverage Diff @@
## main #1713 +/- ##
==========================================
- Coverage 82.19% 82.19% -0.01%
==========================================
Files 161 161
Lines 14999 14997 -2
==========================================
- Hits 12329 12327 -2
Misses 2235 2235
Partials 435 435
Flags with carried forward coverage won't be shown. Click here to find out more. |
Description
This PR adds the ability for developers to check for broken link references in markdown files locally and it also integrates markdown link checking into the CI/CD process of this repository.
Details
Local development
This set of changes adds two Makefile targets
tool which is able to check whether links are alive
all .md (markdown) files in the project. The bin directory is
excluded
markdown-link-check is able to check:
mailto:linksAdditionally, a markdown-link-check configuration file
.markdown-link-check/markdown-link-check-config.jsonrelativeto the project's root has been added. This file can be used
when running the markdown-link-check tool with the
-cflagreferencing it. The
lint/markdown-link-checkMakefile targetmakes use of it automatically.
Some URL patterns have been configured to be ignored in the
markdown-link-check configuration file. This URL patterns
correspond to URLs that resolve to private IP addresses or that
are private GitHub/GitLab repositories.
CI/CD process
Two GitHub workflows have been added that perform Markdown links
checking:
in each PR.
Weekly on Mondays at 07:00 UTC.
All the specified md files and directories in the workflows are
intentionally checked, independently on whether they have been
modified or not. The reason for this is that even if a given .md
file has not been modified, its links can become broken. For example,
if a PR moves .md files from directories and some other .md files
contain relative links referencing the old path of the moved files,
then the links become broken even though the file containing the
references not being modified.
Verification Steps
make lint/markdown-lint-check. No errors should be reported.Checklist (Definition of Done)